OpenApi 和Swagger

什么是OpenAPI

OpenAPI规范（其前身叫Swagger规范）是Linux基金会的一个开源项目，试图通过定义一种用来描述API格式或API定义的语言，来规范RESTful服务开发过程。OpenAPI规范规定了一个API必须包含的基本信息，这些信息包括包括：

 有关API的一般性描述，也就是API的功能介绍
 每个路径上的可用操作(GET、POST等)
 可用路径（资源） ，uri。
 每个操作的输入/返回的参数及其格式，
 验证方法
 联系信息、许可、使用条款和其他附加信息

为什么要使用OpenAPI，它解决了什么问题？

OpenAPI/Swagger 提供了一个全新的维护 API 文档的方式。
随着sprnigboot、springcloud等微服务的流行，在微服务的设计下，小公司微服务小的几十，大公司大的几百上万的微服务。
这么多的微服务必定产生了大量的接口调用。而接口的调用就必定要写接口文档。
在微服务的盛行下，成千上万的接口文档编写，不可能靠人力来编写.
如果依靠人力手工维护接口和文档，我们的接口和文档内容无法保证同步更新，如果我们修改了接口，而忘了修改接口文档，那么其他对接开发人员将无法从文档中获取正确的接口信息，导致无法成功调用接口，这样一来，我们不得不一边开发接口，一边又要劳心费力的维护接口文档。

故OpenAPI/Swagger就产生了，就是为了解决文档和接口的同步问题，它采用自动化实现并解决了人力编写接口文档的问题；
它通过在接口及实体上添加几个注解的方式就能在项目启动后自动化生成接口文档。
以前开发库的时候，每次修改一个函数的参数，都要同时修改两个地方：源文件和头文件。
OpenAPI/Swagger可以实现把源文件的改动自动反映到接口文档。省去了大量的繁琐工作。
它可以根据我们的接口信息自动生成符合RESTful API接口标准的接口文档，配合Swagger-UI可以方便展示接口信息，并且可以在线直接运行测试用例来进行接口测试，可谓一举多得。

描述API自身结构是OpenAPI最根本的能力，编写完成后，OpenAPI规范和Swagger工具可以通过各种方式进一步推动您的API开发：

 使用Swagger Codegen为你的API生成服务器存根，剩下的事情就是实现你的服务器端逻辑。
 使用Swagger Codegen为你的API生成客户端代码库，目前已涵盖了40多种语言。
 使用Swagger UI生成交互式API文档，使用用户可以直接在浏览器中尝试API调用。
 使用规范将API相关工具连接到API。例如，将规范导入SoapUI以为您的API创建自动化测试。