Swagger的生成接口文档

Swagger的生成接口文档

一、背景

前后端之间约定好使用Restful风格的API进行数据通信，此时如果我们能够提供一份清晰明了的接口文档，能够极大的提高效率,既满足我们输出文档的需要又能随代码的变更自动更新

二、使用三步骤

（1）按照swagger要求给接口代码添加声明式注释，具体参照声明式注释格式；

（2）使用swag工具扫描代码自动生成API接口文档数据；

（3）使用gin-swagger渲染在线接口文档页面；

注：相关资源

//文档API
https://swaggo.github.io/swaggo.io/declarative_comments_format/general_api_info.html
//获取依赖
go get -u github.com/swaggo/swag/cmd/swag

三、分步讲解

1、添加注释

（1）主函数添加注释

//@title TestSwagger0 
//@version 1.0
//@description This my test Swagger
//@termsOfService http://swagger.io/terms/
//@contact.name Moe
//@contact.url http:///192.168.93.128:8080/api/v1/post
//@contact.email support@swagger.io
//@license.name Apache 2.0
//@host 192.168.93.128:8080
//@BasePath /api/v1

（2）在接口中添加注释

// LoginHandler testPostHandler
// @Summary testSummary
    #操作简要描述（eg:通过用户名获取密码）
// @Description testSummaryDescription
   #操作详细说明
// @Tags testTags
   #接口分类信息标签（在接口上描述,相当于给接口分组）
// @Accept application/json
  #接收请求的编码类型
// @Produce application/json
   #返回响应的类型
// @Param object query Model.Param  false "Params"
   #参数信息使用空格分隔
   1.参数名
   2.参数类型，可以有的值是 formData、query、path、body、header，formData 表示是 post 请求的
   数据，query 表示带在 url 之后的参数，path 表示请求路径上得参数，例如上面例子里面的 key，body
   表示是一个 raw 数据请求，header 表示带在 header 信息中得参数。
   3.参数类型
   4.是否必须
   5.注释
举例说明： @Param name query string true "用户姓名"
// @Security ApiKeyAuth
// @Success 200 {string} string "返回"
#成功返回给客户端的信息，三个参数
第一个是返回状态码
第二个参数是返回的类型，必须使用 {} 包含
object (struct)
string (string)
integer (int, uint, uint32, uint64)
number (float32)
boolean (bool)
array
第三个是返回的对象或者字符串信息
三个参数必须通过空格分隔
// @Router /post [post]
#路由信息，包含两个参数，使用空格分隔
第一个是请求的路由地址，支持正则和自定义路由，和之前的路由规则一样
第二个参数是支持的请求方法,放在 [] 之中，如果有多个方法，那么使用 , 分隔。

注：添加注释的时候不能留白

2、安装swag并初始化

go get -u github.com/swaggo/swag/cmd/swag
swag init

之后会出现docs文档

3、router中引入docx包以及相关依赖

import (
	_ "SwaggerDemo/docs"
	"github.com/gin-gonic/gin"
	gs "github.com/swaggo/gin-swagger"
	"github.com/swaggo/gin-swagger/swaggerFiles"
)

4、在router中注册路由

r.GET("/swagger/*any", gs.WrapHandler(swaggerFiles.Handler))

使用http://localhost:8080/swagger/index.html查看文档

如果看完对自己有所帮助，请点赞支持