gin-swagger

关于 Swagger 官网

Swagger 文档提供了一个方法,使我们可以用指定的 JSON 或者 YAML 摘要来描述你的 API, 包括了比如 names、order 等 API 信息。

你可以通过一个文本编辑器来编辑 Swagger 文件,或者你也可以从你的代码注释中自动生成。 各种工具都可以使用 Swagger 文件来生成互动的 API 文档。

注意:用 Swagger 文件生成互动的 API 文档是最精简的,它展示了资源、参数、请求、响应。但是它不会提供你的API如何工作的其他任何一个细节。

我这里介绍的是 gin-swagger

source

首先需要本地安装 swag

1、go get

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

若 $GOPATH/bin 没有加入$PATH中,你需要执行将其可执行文件移动到$GOBIN下

mv $GOPATH/bin/swag /usr/local/go/bin

2、gopm get 该包有引用golang.org上的包,若无科学上网,你可以使用 gopm 进行安装

gopm get -g -v github.com/swaggo/swag/cmd/swag

cd $GOPATH/src/github.com/swaggo/swag/cmd/swag

go install
同理将其可执行文件移动到$GOBIN下

3、 验证是否安装成功

$ swag -v
swag version v1.1.1
编辑API注释

Swagger 中需要将相应的注释或注解编写到方法上,再利用生成器自动生成说明文件 gin-swagger 给出的范例:

// @Summary Add a new pet to the store
// @Description get string by ID
// @Accept  json
// @Produce  json
// @Param   some_id     path    int     true        "Some ID"
// @Success 200 {string} string "ok"
// @Failure 400 {object} web.APIError "We need ID!!"
// @Failure 404 {object} web.APIError "Can not find ID"
// @Router /testapi/get-string-by-int/{some_id} [get]

我们可以参照 Swagger 的注解规范和范例去编写

 // @Summary 新增文章标签
 // @Produce  json
 // @Param name query string true "Name"
 // @Param state query int false "State"
 // @Param created_by query int false "CreatedBy"
 // @Success 200 {string} json "{"code":200,"data":{},"msg":"ok"}"
 // @Router /api/v1/tags [post]
 func AddTag(c *gin.Context) {


 // @Summary 修改文章标签
 // @Produce  json
 // @Param id path int true "ID"
 // @Param name query string true "ID"
 // @Param state query int false "State"
 // @Param modified_by query string true "ModifiedBy"
 // @Success 200 {string} json "{"code":200,"data":{},"msg":"ok"}"
 // @Router /api/v1/tags/{id} [put]
 func EditTag(c *gin.Context) {
生成

进入项目根目录中,执行初始化命令

➜  logic git:(master) swag init  
2019/04/02 15:12:32 Generate swagger docs....
2019/04/02 15:12:32 Generate general API Info
2019/04/02 15:12:32 create docs.go at  docs/docs.go
2019/04/02 15:12:32 create swagger.json at  docs/swagger.json
2019/04/02 15:12:32 create swagger.yaml at  docs/swagger.yaml

完毕后会在当前目录下生成docs

  docs/
  ├── docs.go
  └── swagger
      ├── swagger.json
      └── swagger.yaml

初始化swagger

  func AddSwaggerRoute(r *gin.Engine, options *conf.Config) {
    docs.SwaggerInfo.Title = "Badger API"
    docs.SwaggerInfo.Description = "Badger server."
    docs.SwaggerInfo.Version = "1.0"
    docs.SwaggerInfo.Host = options.SwaggerOptions.Domain + options.HttpOptions.HttpPort
    docs.SwaggerInfo.BasePath = options.SwaggerOptions.BasePath
    r.GET(options.SwaggerOptions.SwaggerPath, ginSwagger.WrapHandler(swaggerFiles.Handler))
  }

API注释示例

package user

import (
    ...
)

// @Summary index POST
// @Description 测试服务是否正常
// @Tags user
// @Accept  json
// @Produce  json
// @Param user body model_user.User true "user info"
// @Security ApiKeyAuth
// @Success 200 {string} json "{"data":{},"code":200,"msg":""}"
// @Router  /index   [post]

func Create(c *gin.Context) {
    ...
}  
语法说明: