Gin与OpenAPI(Swagger)的使用

一、背景

1、swagger与openapi

      Swagger：       

        一种用于描述RESTFUL API的规范，它提供了一种简单的来描述API的请求和相应参数、错误码、返回数据类型等信息，是开发者可以方便了解API使用方式。

         官网: https://swagger.io/

     OpenAPI :

        始于 Swagger 规范，Swagger 规范已于 2015 年捐赠给 Linux 基金会后改名为 OpenAPI，并定义最新的规范为 OpenAPI 3.0。
        OpenAPI 规范（OAS）是一种通用的、和编程语言无关的 API 描述规范，使人类和计算机都可以发现和理解服务的功能，而无需访问源代码、文档或针对接口进行嗅探。正确定义后，使用者可以使用最少的实现逻辑来理解远程服务并与之交互。

        官网: https://www.openapis.org/

2、API设计优先的理念优势

        我们在实际前后端开发的过程中，其实前后端可以并行开发，这样可以缩短我们的项目工期，提高工作效率。但是，并行工作的前提是，前端知道后端要返回怎么样的接口数据，后端知道前端需要怎么样的数据。  由此， 前后端必须先对API结构进行一个"约定", 约定需要哪些接口、接口的URL、接口的参数、接口的响应等参数，明确后，双方基于这个接口文档/接口约定进行开发。

        但是前端，开发过程中，后端接口还没做好，怎么对接呢? 此时由于我们已经将接口内容定下来了，所以，此时我们希望有一种工具能够给一些模拟的数据，前端先针对这些模拟数据进行Mock开发。 最后前后端开发差不多了，直接将API的URL地址改为后端地址，即可完成开发，转而进行后续测试、部署，极大提高了我们的开发效率。

        所以一般前后端开发基于OpenAPI的方式，步骤如下:

        1、API设计优先的理念就是， API是一份前后端开发的”契约”, 前后端先进行数据接口展示和获取的定义， 也就是定义输入、正常输出、异常输出等情况API的输入参数、输出数据格式。 最后双方再基于API契约进行代码的实现

        2、后端根据API接口进行编码， 前端可以通过Mock程序模拟后端返回(按照API定义的请求、响应数据类型格式)进行随机数填充

        3、前后端可以同时基于契约进行并行开发，最后前后端都开发OK了，前端再将API地址从Mock服务器改为测试服务器地址，最后进行调试整合即可

二、API设计的相关工具

        关于API设计的相关工具可以参考这个站点: https://openapi.tools/

1、API文档可视化编辑器(stoplight-studio)

        如果我们是手动编辑OpenAPI的yaml文档来生成接口文档，这个确实效率比较低。人工编写API的yaml文件，工作量太大，我们可以使用可视化工具对OpenAPI的规范文件进行设计， 最终生成yaml文件. 此时，我们期望有一种可视化工具，通过可视化工具配置，即可完成这个过程。那么这个工具就是stoplight-studio:     

2、提供给消费者(前端)的Mock服务工具(Prism)

        前面我们讲过，前端不能干等着后端开发完所有接口才能开始进行对接。那么此时，我们前端需要获取后端的模拟数据，这个Mock工具就是Prism。 它可以根据我们定义的OpenAPI文档，数据的响应格式、数据类型，返回模拟数据进行填充，这样就模拟完成前后端对接的工作。 无须等待后端全部完成工作才进行对接。 最后很简单，当前后端完成后，前端将URL地址换成后端地址即可.

3、提供给生产者(后端)的Code代码生成工具(OpenAPI Generator)

        针对后端来说，我们需要根据OpenAPI的URL、参数、响应编写后端代码。 此时后端的同学也想提高效率，有没有根据文档一键生成后端框架代码的工具呢? 答案是肯定的。 例如Golang的Gin框架，可以通过此工具根据OpenAPI的文档yaml文件生成route路由代码，可以提高我们的工作效率。

 三.代码转OpenAPI文档

1、优势

        这个工具是我们场景的应用场景。 我们后端在编写接口的时候，往往都会将这个接口的相关文档编写到一个专门记录这些接口的文档工具进行记录。例如Yapi等这些平台。

        但是这种方式往往存在一些问题，那就是，每次更新完代码以后，忘记更新了Yapi的文档或者漏更新了文档，导致文档和最新代码不一致。

        此时我们可以借助代码框架集成swagger、openapi的方式，通过编写代码的时候，顺带通过注解的方式，将接口的相关信息写上，最后在发布项目的时候，自动生成swagger文档，这样可以有利于对文档的实时更新，写代码的时候顺带将文档写上了，一举两得。

2、Gin框架配置Swagger

开源项目地址: https://github.com/swaggo/gin-swagger

1、安装依赖

go install github.com/swaggo/swag/cmd/swag@latest
go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/files

2、swag init初始化docs目录

执行命令: swag init
会生成docs目录， 目录里存在swagger api的yaml配置文件以及json相关文件

3、接口添加相关注解

4、main.go配置swagger路由信息

5、swag init 且 运行程序(每次代码更新，需要swag init生成新的文档)

四、总结

        从上文我们可以发现OpenAPI的文档yaml可以转换为对应框架的代码， 对应的框架代码也可以生成yaml文档。

        其实除了上面说的:

        1、基于文档契约，前后端可以并行工作

        2、文档和代码可以直接放在一起进行维护，保持文档与代码的准确性

        其实还有一种场景，例如之前你们一直按照这种OpenAPI或者Swagger的方式进行开发，最初使用的是PHP、或者Python， 现在由于业务发展， 需要更加高性能的实现， 转换为Go或者Java， 那么此时，我们只需要拿到OpenAPI/Swagger的yaml文件，通过工具生成对应Go、Java框架路由代码， 参数、路由、响应数据格式都一键生成，自己再实现接口逻辑即可。

        不需要自己再慢慢看文档来从头到尾实现。