项目开发-swagger篇
OpenAPI规范
OpenAPI 规范（OpenAPI Specification），是定义一个标准的、与具体编程语言无关的RESTful API的规范。
RESTful (REpresentational State Transfer)风格是一种基于HTTP协议设计Web API的软件架构风格，由Roy Fielding在2000年提出。它强调使用HTTP动词来表示对资源的操作（GET、POST、PUT、PATCH、DELETE等），并通过URI表示资源的唯一标识符。
OpenAPI 规范可以在“不接触任何程序源代码和文档、不监控网络通信”的情况下理解一个服务的作用。遵循 OpenAPI 规范来定义 API，以使用文档生成工具来展示。主要的Swagger工具包括：
- Swagger Editor：基于浏览器的编辑器，可以在其中编写 OpenAPI 定义。
- Swagger UI：将 OpenAPI 定义渲染为交互式文档。
- Swagger Codegen：根据 OpenAPI 定义生成服务器存根和客户端库。
- Swagger Editor Next (beta)：基于浏览器的编辑器，可以在其中编写和审查 OpenAPI 和 AsyncAPI 定义。
- Swagger Core：用于创建、使用和处理 OpenAPI 定义的 Java 相关库。
- Swagger Parser：用于解析 OpenAPI 定义的独立库
- Swagger APIDom：为描述各种描述语言和序列化格式的 API 提供单一、统一的结构。
Swagger
Swagger 是一套围绕 OpenAPI 规范构建的开源工具，可帮助开发人员设计、构建、记录和使用 REST API，支持文档在线自动生成以及接口功能测试。基于OpenAPI规范编写注解或通过扫描代码去生成注解，就能生成统一标准的接口文档和一系列 Swagger 工具。
以下以go swagger为例，说明如何为代码自动生成接口文档。
环境准备
安装swgger
go install github.com/swaggo/swag/cmd/swag@latest
支持的web框架
gin
buffalo
net/http
...
swagger使用
接口文档的生成过程：首先按照规范给接口代码（controller层）添加声明式注释，接着使用swagger工具扫描代码自动生成api接口文档数据，然后渲染在线接口文档页面。
添加注释
注释规范说明
@Summary 摘要
@Description 详细的说明
@Tags 每个API操作的标签列表，以逗号分隔。
@Accept API可以使用的MIME类型列表，只影响具有请求正文的操作，例如POST、PUT、PATCH
@Produce 可以产生的 MIME 类型列表，MIME 类型可以简单的理解为响应类型，例如：json、xml、html 等等
@Param 参数格式，从左到右分别为：参数名、入参类型、数据类型、是否必填、注释
@Success 响应成功，从左到右分别为：状态码、参数类型、数据类型、注释
@Failure 响应失败，从左到右分别为：状态码、参数类型、数据类型、注释
@Router 路由，从左到右分别为：路由地址，HTTP 方法
具体例子
// ShowAccount godoc
//
// @Summary Show an account
// @Description get string by ID
// @Tags accounts
// @Accept json
// @Produce json
// @Param id path int true "Account ID"
// @Success 200 {object} model.Account
// @Failure 400 {object} httputil.HTTPError
// @Failure 404 {object} httputil.HTTPError
// @Failure 500 {object} httputil.HTTPError
// @Router /accounts/{id} [get]
// UploadAccountImage godoc
//
// @Summary Upload account image
// @Description Upload file
// @Tags accounts
// @Accept multipart/form-data
// @Produce json
// @Param id path int true "Account ID"
// @Param file formData file true "account image"
// @Success 200 {object} controller.Message
// @Failure 400 {object} httputil.HTTPError
// @Failure 404 {object} httputil.HTTPError
// @Failure 500 {object} httputil.HTTPError
// @Router /accounts/{id}/images [post]
生成接口文档
在包含main.go文件的项目根目录运行swag init，解析注释并生成需要的文件（docs文件夹和docs/docs.go）
# swag 生成命令
swag init .
如果部分接口不需要生成接口文档，则使用排除命令。
# swag 排除命令
swag init -d ./ --exclude ./app/api/v2
确保导入了生成的docs/docs.go文件，这样特定的配置文件才会被初始化。
//注册路由处
import (
_ "xxx/docs" //导入生成的docs
)
(可选) 可以使用fmt格式化 SWAG 注释。
swag fmt
渲染文档数据
注册swagger api相关路由，可以自定义文档格式，也可使用现有工具的渲染，例如gin-swagger的swaggerFiles.Handler
swagger := e.Group("swagger", middleware.SwaggerBasicAuth())
{
swagger.GET("/*any", api.Swagger.HandleReDoc)
}
项目运行后，浏览器访问定义的文档地址即可查看
Swag cli
swag init -h
NAME:
swag init - Create docs.go
USAGE:
swag init [command options] [arguments...]
OPTIONS:
--generalInfo value, -g value API通用信息所在的go源文件路径，如果是相对路径则基于API解析目录 (默认: "main.go")
--dir value, -d value API解析目录 (默认: "./")
--exclude value 解析扫描时排除的目录，多个目录可用逗号分隔（默认：空）
--propertyStrategy value, -p value 结构体字段命名规则，三种：snakecase,camelcase,pascalcase (默认: "camelcase")
--output value, -o value 文件(swagger.json, swagger.yaml and doc.go)输出目录 (默认: "./docs")
--parseVendor 是否解析vendor目录里的go源文件，默认不
--parseDependency 是否解析依赖目录中的go源文件，默认不
--markdownFiles value, --md value 指定API的描述信息所使用的markdown文件所在的目录
--generatedTime 是否输出时间到输出文件docs.go的顶部，默认是
--codeExampleFiles value, --cef value 解析包含用于 x-codeSamples 扩展的代码示例文件的文件夹，默认禁用
--parseInternal 解析 internal 包中的go文件，默认禁用
--parseDepth value 依赖解析深度 (默认: 100)
--instanceName value 设置文档实例名 (默认: "swagger")
swag fmt -h
NAME:
swag fmt - format swag comments
USAGE:
swag fmt [command options] [arguments...]
OPTIONS:
--dir value, -d value API解析目录 (默认: "./")
--exclude value 解析扫描时排除的目录，多个目录可用逗号分隔（默认：空）
--generalInfo value, -g value API通用信息所在的go源文件路径，如果是相对路径则基于API解析目录 (默认: "main.go")
--help, -h show help (default: false)
版权声明：本博客所有文章除特别声明外，均采用 CC BY 4.0许可协议，转载请注明出处
本文链接：https://blog.redamancy.tech/technique/22