Go开源宝藏Go-Swagger 自动生成 api 接口文档

Posted 2021-12-05 小生凡一

Go-Swagger

• 写在前面
• 1. 使用
• 2. API 注释介绍
• 3. 请求部分
• 4. 响应部分

写在前面

• 安装

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

Go-Swagger 可以用来自动生成接口文档，减少大家编写接口文档的时间。

1. 使用

先下载驱动

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

1. 头部导入

• 放在main函数中

// @title ToDoList API
// @version 0.0.1
// @description This is a sample Server pets
// @securityDefinitions.apikey ApiKeyAuth
// @name FanOne
// @BasePath /api/v1

2. 在终端运行

swag init -g main.go

3. 会发现新的文件
   
4. 在路由层引入

import (
	swaggerFiles "github.com/swaggo/files"
	ginSwagger "github.com/swaggo/gin-swagger"
	_ "to-do-list/docs" // 这里需要引入本地已生成文档
)

5. 开启swag

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

6. 然后就可以在api里面进行写注释了

7. 注意每次写完要重新运行

swag init -g main.go

再重新启动程序

8. 就会在这个网址展示出来接口文档了！

我的是3000端口，所以是这个。

http://localhost:3000/swagger/index.html

2. API 注释介绍

// @summary 服务连接校验 --> 接口简介
// @Description 服务初始连接测试 --> 接口描述
// @Accept json   --> 请求接收类型
// @Produce json  --> 请求返回类型
// @Produce string  --> 请求返回类型 (可以设置多条)
// @Params userId query string true "用户id" minlength(3) maxlength(100)
// Success 200 {object} Response --> 成功后返回数据结构
// Failure 400 {object} ResponseError --> 失败后返回数据结构
// Failure 404 {object} ResponseError
// Failure 500 {object} ResponseError
// @Router /check [get] --> 路由地址及请求方法

3. 请求部分

• Params

格式: [ 参数名称 参数类型 数据类型 是否必须 备注 限制属性 ] 空格分割

@Params user_name query string true "用户姓名" minlength(3) maxlength(100)
@Params password query string true "密码" minlength(7)
@Params status query integer false "状态：0 1" Enums(0, 1) defualt(0)

• 参数可用类型 [param type]

  • query

  @Params password query string true "密码" minlength(7)
  

  • path

  @Params id path uint true "用户id" minlength(1)
  

  • header

  @Params authorization header string true "鉴权" 
  

  • body
  • formDate

• 数据可用类型 [data type]

  • string(string)
  • integer(int, uint, uint32, uint64)
  • boolean(bool)
  • struct

• 可配置属性

参数	属性
defualt *	参数默认值
maximum number	最大值
mininum number	最小值
maxLength integer	最大长度
minLength integer	最小长度
enums [*]	枚举类型

4. 响应部分

• 定义响应结构体

package serializer

type ResponseUser struct {
	Status int `json:"status" example:"200"`
	Data User `json:"data"`
	Msg string `json:"msg" example:"ok"`
	Error string `json:"error" example:""`
}

type ResponseTask struct {
	Status int `json:"status"`
	Data Task `json:"data"`
	Msg string `json:"msg"`
	Error string `json:"error"`
}

• success 成功响应 格式: [ 状态码 {数据类型} 数据类型 备注 ]

// @Success 200 {object} serializer.ResponseUser "成功"

• failure 失败响应 格式: [ 状态码 {数据类型} 数据类型 备注 ]

// @Failure 500 {object} serializer.ResponseError "失败"