swagger

文档

《swag文档（中文）》

格式化注释代码：swag fmt

生成文档：swag init

通用API注释

注释分为通用API注释和API注释，通用API注释用于全局性的配置，API注释用于为单个接口生成接口文档。

// @title           Swagger Example API
// @version         1.0
// @description     This is a sample server celler server.
// @termsOfService  http://swagger.io/terms/

// @contact.name   API Support
// @contact.url    http://www.swagger.io/support
// @contact.email  support@swagger.io

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

// @host      localhost:8080
// @BasePath  /api/v1

// @securityDefinitions.basic  ApiKeyAuth
func main(){

}

指定接口文档的鉴权方式为 JWT token 方式

// @securityDefinitions.apikey ApiKeyAuth
// @in                         header
// @name                       x-token

// @contact.name、@license.name 之类可以不要。

// @host localhost:8080 可以动态配置，更灵活。

动态通用 API 注释

package main

import (
    "github.com/gin-gonic/gin"
    "github.com/swaggo/files"
    "github.com/swaggo/gin-swagger"

    "./docs" // docs is generated by Swag CLI, you have to import it.
)

// @contact.name   API Support
// @contact.url    http://www.swagger.io/support
// @contact.email  support@swagger.io

// @license.name  Apache 2.0
// @license.url   http://www.apache.org/licenses/LICENSE-2.0.html
func main() {

    // programatically set swagger info
    docs.SwaggerInfo.Title = "Swagger Example API"
    docs.SwaggerInfo.Description = "This is a sample server Petstore server."
    docs.SwaggerInfo.Version = "1.0"
    docs.SwaggerInfo.Host = "petstore.swagger.io"
    docs.SwaggerInfo.BasePath = "/v2"
    docs.SwaggerInfo.Schemes = []string{"http", "https"}

    r := gin.New()

    // use ginSwagger middleware to serve the API docs
    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

    r.Run()
}

API 注释

Mime 类型

// @accept   x-www-form-urlencoded
// @produce  json

Alias	MIME Type
json	application/json
xml	text/xml
plain	text/plain
html	text/html
mpfd	multipart/form-data
x-www-form-urlencoded	application/x-www-form-urlencoded
json-api	application/vnd.api+json
json-stream	application/x-json-stream
octet-stream	application/octet-stream
png	image/png
jpeg	image/jpeg
gif	image/gif

@param 参数类型

1. query：查询参数

   // @param       page     query    int false "page，从0开始，默认0"

2. path：路径参数

   // @router      /user/{id} [get]
   // @param       id         path  int true "ID"

3. formData：表单

   // @param       title   formData string false "标题"

4. header：请求头

5. body：请求体

@param 数据类型

1. string (string)

   // @param       title   formData string false "标题"

2. integer (int, uint, uint32, uint64)

   // @param       id      path     int    true  "ID"

3. number (float32)

4. boolean (bool)

5. user defined struct

6. file

token 鉴权

1. 在通用 API 注释中，指定接口文档的鉴权方式为 JWT token 方式。加了这个注释，就可以在生成的接口文档中指定测试用的 token。

// @securityDefinitions.apikey ApiKeyAuth
// @in                         header
// @name                       x-token

2. 在 API 注释中，指定需要 token（不需要 token 的接口，不用写这个注释）。加了这个注释，会使生成的接口文档中，点击请求接口时，验证是否已填写了 token。

// @security    ApiKeyAuth

3. 在 Go 代码中进行 token 验证。这里才是 token 逻辑实际生效的地方，前面的注释只是为了测试用。

app.GET("/user/info", middleware.Jwt, user.UserInfo)