Swagger2 权威指南——前言

前言

接口文档作为软件开发过程中有着非常重要的作用，它可以作为开发及测试人员系统工作的重要依据，特别是在目前流行的前后端分离开发模式中，接口文档更是作为前后端开发人员协同开发，以及测试人员编写测试用例的重要参考文档。而记录接口文档的形式多种多样，一般常用的接口文档采用以下形式：

• 口口相传
• 使用world或其他文本文件进行保存
• 使用wiki编写
• 使用Postman

以上几种方式都存在一个致命的缺点——文档同步问题，即我们的接口和文档内容无法保证同步更新，如果我们修改了接口，而忘了修改接口文档，那么其他对接开发人员将无法从文档中获取正确的接口信息，导致无法成功调用接口，这样一来，我们不得不一边开发接口，一边又要劳心费力的维护接口文档，无端增加了很多工作量，因此我们迫切需要一种手段来解决这个问题。

Swagger是一款基于OpenAPI标准编写的用于生成标准RESTful API接口文档的开源框架，它可以根据我们的接口信息自动生成符合RESTful API接口标准的接口文档，配合Swagger-UI可以方便展示接口信息，并且可以在线直接运行测试用例来进行接口测试，可谓一举多得。此外，围绕Swagger有很多生态工具支持，如Swagger UI、Swagger Editor、Swagger Validator、Swagger Codegen等。

在笔者编写本文时OpenAPI规范已经更新到了3.0，因此笔者文章中所有实例均是基于OpenAPI规范3.0，如果想要了解OpenAPI 2.0，可以访问：https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md