Golang项目自动生成swagger格式接口文档方法(一)

开发 开发工具
Swag是一款可以将Go的注释转换为Swagger2.0格式文档的工具,生成接口文档用到的注释需要按照swag要求的格式书写。

swag工具介绍和安装

Swag是一款可以将Go的注释转换为Swagger2.0格式文档的工具,生成接口文档用到的注释需要按照swag要求的格式书写。

使用go install方式下载安装swag

$ go install github.com/swaggo/swag/cmd/swag@latest

也可以从github的release页面下载编译好的二进制文件,以1.8.10版本为例:

$ wget https://github.com/swaggo/swag/releases/download/v1.8.10/swag_1.8.10_Linux_x86_64.tar.gz
$ tar zxvf swag_1.8.10_Linux_x86_64.tar.gz
$ chmod +x ./swag
$ mv swag /usr/local/bin

在包含main.go文件的项目根目录运行swag init将会解析注释并生成文件(docs文件夹),修改对应注释后再次运行swag ini即可:

swag init

使用swag fmt可以格式化SWAG注释:

swag fmt

符合swag要求的API通用注释写法

在main.go的main方法添加API通用注释

// @title         idcenter API
// @version 1.0
func main() {
//...
}

更多通用注释字段说明和示例:

注释

说明

示例

title

必填 应用程序的名称。

// @title Swagger Example API

version

必填 提供应用程序API的版本。

// @version 1.0

description

应用程序的简短描述。

// @description This is a sample server celler server.

tag.name

标签的名称。

// @tag.name This is the name of the tag

tag.description

标签的描述。

// @tag.description Cool Description

tag.docs.url

标签的外部文档的URL。

// @tag.docs.url ​https://example.com​

tag.docs.description

标签的外部文档说明。

// @tag.docs.description Best example documentation

termsOfService

API的服务条款。

// @termsOfService ​http://swagger.io/terms/​

contact.name

公开的API的联系信息。

// @contact.name API Support

contact.url

联系信息的URL。 必须采用网址格式。

// @contact.url ​http://www.swagger.io/support​

contact.email

联系人/组织的电子邮件地址。 必须采用电子邮件地址的格式。

// @contact.email support@swagger.io

license.name

必填 用于API的许可证名称。

// @license.name Apache 2.0

license.url

用于API的许可证的URL。 必须采用网址格式。

// @license.url ​http://www.apache.org/licenses/LICENSE-2.0.html​

host

运行API的主机(主机名或IP地址)。

// @host localhost:8080

BasePath

运行API的基本路径。

// @BasePath /api/v1

accept

API 可以使用的 MIME 类型列表。 请注意,Accept 仅影响具有请求正文的操作,例如 POST、PUT 和 PATCH。 值必须如“Mime类型”中所述。

// @accept json

produce

API可以生成的MIME类型的列表。值必须如“Mime类型”中所述。

// @produce json

query.collection.format

请求URI query里数组参数的默认格式:csv,multi,pipes,tsv,ssv。 如果未设置,则默认为csv。

// @query.collection.format multi

schemes

用空格分隔的请求的传输协议。

// @schemes http https

externalDocs.description

Description of the external document.

// @externalDocs.description OpenAPI

externalDocs.url

URL of the external document.

// @externalDocs.url ​https://swagger.io/resources/open-api/​

x-name

扩展的键必须以x-开头,并且只能使用json值

// @x-example-key {"key": "value"}

符合swag要求的具体API注释

在接口的handler方法中添加具体的API注释。

//  Login godoc
// @Summary 登录
// @Schemes https
// @Description 登录
// @Tags account
// @accept json
// @Produce json
// @Param account body param.LoginReq true "login"
// @Success 200 {object} param.JSONResult{data=param.LoginRes}
// @Router /user/login [post]
func Login(g *gin.Context) {
//...
}

参数注释和返回注释支持结构体,本例中用到的结构体在param包下面,内容如下:

// JSONResult response body结构
type JSONResult struct {
Code int `json:"code" binding:"required"`
Data interface{} `json:"data" binding:"required"`
Msg string `json:"msg" binding:"required"`
}

// LoginReq 登录接口入参
type LoginReq struct {
Email string `json:"email" binding:"required,min=6,max=50"` // 邮箱
Password string `json:"Password" binding:"required,min=8,max=15"` // 密码
}

// LoginRes 登录接口返回参数
type LoginRes struct {
Token json:"token"` // token
}

更多注释字段说明:

注释

描述

description

操作行为的详细说明。

description.markdown

应用程序的简短描述。该描述将从名为endpointname.md的文件中读取。

id

用于标识操作的唯一字符串。在所有API操作中必须唯一。

tags

每个API操作的标签列表,以逗号分隔。

summary

该操作的简短摘要。

accept

API 可以使用的 MIME 类型列表。 请注意,Accept 仅影响具有请求正文的操作,例如 POST、PUT 和 PATCH。 值必须如“Mime类型”中所述。

produce

API可以生成的MIME类型的列表。值必须如“Mime类型”中所述。

param

用空格分隔的参数。param name,param type,data type,is mandatory?,comment attribute(optional)

security

每个API操作的安全性

success

以空格分隔的成功响应。return code,{param type},data type,comment

failure

以空格分隔的故障响应。return code,{param type},data type,comment

response

与success、failure作用相同

header

以空格分隔的头字段。 return code,{param type},data type,comment

router

以空格分隔的路径定义。 path,[httpMethod]

x-name

扩展字段必须以x-开头,并且只能使用json值。

生成接口文档

按照swag要求写好注释后,执行如下命令生成文档。

swag init

会在根目录生成docs文件夹,里面包含swagger.json,、swagger.yaml和doc.go三个文件。

责任编辑:姜华 来源: 今日头条
相关推荐

2023-03-08 08:48:50

Swag工具

2023-09-21 10:44:41

Web服务Swagger前端

2017-07-20 17:05:04

JavaScriptswagger-decSwagger

2017-06-20 15:39:58

Koa2 应用动态Swagger文档

2023-08-09 08:37:44

2020-12-07 06:05:34

apidocyapiknife4j

2020-08-06 11:45:37

数据库文档Swagger

2023-03-20 08:24:31

工具GoReleaser

2021-04-16 07:31:50

工具Postman接口

2022-02-16 08:21:11

JavaSwagger工具

2009-12-17 09:31:02

Ruby on Rai

2023-08-02 09:07:27

Golangio 包

2009-07-23 13:35:33

Ruby on Rai

2009-06-29 17:03:41

自动生成Getter和Eclipse

2023-03-15 08:42:06

form表单设计接口

2024-01-01 13:27:44

pydoc工具代码

2017-08-10 16:14:07

FeignRPC模式

2022-06-01 09:51:51

Golang方法接收者

2023-11-02 09:54:21

ODT文件

2023-05-05 07:49:07

GolangJSON格式
点赞
收藏

51CTO技术栈公众号