转载

goswagger入门手册

本文旨在记录使用goswagger过程中遇到的一些问题（只在生成文档方面，不涉及其他功能）：

如何在go1.11+以上（支持Go Module）版本中的应用swagger
一些注解上的注意事项
如何在团队中管理API文档（主要涵盖了：swagger-ui的部署和使用）

关于 swagger

swagger涵盖WebAPI的一整套工具：API设计，API实现（代码生成），API文档，API测试及API规范。更多信息请参见官网

准备工作

一个Golang web项目，并软连接到 GOPATH/src 下。【毕竟是支持Gomodule的项目，还放在GOPATH下就不科学了:smile:】
安装swagger工具. 参见安装

环境：

➜  swagger-demo git:(master) ✗ go version
go version go1.11.5 darwin/amd64
➜  swagger-demo git:(master) ✗ swagger version
version: v0.18.0
commit: 6b23bb61413826ce42c3b14a37bf5870caf91e0b

编写注释

元信息包含了这个应用的基本信息。一般新建一个doc.go放在你的API根目录下；还有一定要注意这句话：

You give it a main file and it will parse all the files that are reachable by that main package to produce a swagger specification.To use you can add a go:generate comment to your main file。

//go:generate swagger generate spec

The command requires a main package or file and it wants your code to compile. It uses the go tools loader to load an application and then scans all the packages that are in use by the code base. This means that for something to be discoverable it needs to be reachable by a code path triggered through the main package.

就是说如果你配置好了一切东西，但是却因为你的main包“花里胡哨”，而无法生成文档的时候，记得尝试下这个方法！！！

一般来说，一个API的文档无非包括：请求方法，路由，参数，响应。如下：

// 格式：swagger:parameters 操作ID(也就是标示一个路由的ID)
// swagger:parameters opid-get
type getForm struct {
	// in: query
	ID int `form:"id" binding:"required"`
}

// 格式：swagger:model ?模型名(可选)
// 动手题：为什么还需要额外定义一个模型getmodels来使用？而不是直接在getResponse中使用 []*models.GetModel ?
// swagger:model
type getmodels []*models.GetModel

// 格式：swagger:response 响应结构名
// getResponse response demo of get controller
// swagger:response getResponse
type getResponse struct {
	// code int，这里参数较多自行参照文档，个人觉得比较实用的是 “in: query|body” 用于说明参数存在的位置
	// in: body
	Code int `json:"code"`
	// modesl getmodel
	// in: body
	Models getmodels `json:"models"`
}

// Get ...
func Get(c *gin.Context) {
	// swagger:route GET /base/get 范例 opid-get
	//
	// swagger Get范例
	//
	//
	//     Consumes:
	//     - application/json
	//     - application/x-protobuf
	//
	//     Produces:
	//     - application/json
	//     - application/x-protobuf
	//
	//     Schemes: http, https, ws, wss
	//
	//     Responses:
	//       default: getResponse
	var (
		form = new(getForm)
		resp = new(getResponse)
	)

	resp.Code = 0
	resp.Models = services.ListGetModels()

	log.Println("form is :", *form)
	c.JSON(http.StatusOK, resp)
}

上述只是最基本的关于一个API的基础注释。更多请参见官方文档，尽管它不一定是最新的～

生成API文档（swagger.json）

swagger 生成文档的命令如下：

➜  gonic git:(master) ✗ swagger generate spec -h
Usage:
  swagger [OPTIONS] generate spec [spec-OPTIONS]

generate a swagger spec document from a go application

Application Options:
  -q, --quiet               silence logs
  -o, --output=LOG-FILE     redirect logs to file

Help Options:
  -h, --help                Show this help message

[spec command options]
      -b, --base-path=      the base path to use (default: .)
      -t, --tags=           build tags
      -m, --scan-models     includes models that were annotated with 'swagger:model'
          --compact         when present, doesn't prettify the json
      -o, --output=         the file to write to
      -i, --input=          the file to use as input
      -c, --include=        include packages matching pattern
      -x, --exclude=        exclude packages matching pattern
          --include-tag=    include routes having specified tags (can be specified many times)
          --exclude-tag=    exclude routes having specified tags (can be specified many times)

用于说明的Makefile

gen-doc:
	# 与 v3无异，只是不格式化生成的json文件
	GO111MODULE=off swagger generate spec -o swagger-demo.swagger.final.json -b ./mainC -c swagger-demo -m --compact

gen-doc-v3:
	# 支持扫描 swagger:model
	GO111MODULE=off swagger generate spec -o swagger-demo.swagger.v3.json -b ./mainC -c swagger-demo -m

gen-doc-v2:
	# 如果遇到找不到自己项目内部包的情况，且main包花里呼哨
	GO111MODULE=off swagger generate spec -o swagger-demo.swagger.v2.json -b ./mainC -c swagger-demo

gen-doc-v1:
	# main包花里胡哨，并不是一个单文件
	GO111MODULE=off swagger generate spec -o swagger-demo.swagger.v1.json -b ./mainC

gen-doc-v0:
	# 常规用法（适用于符合goswagger标准的项目）
	GO111MODULE=off swagger generate spec -o swagger-demo.swagger.v0.json

default: gen-doc-v0 gen-doc-v1 gen-doc-v2 gen-doc-v3 gen-doc

管理API文档

生成了swagger.json文件之后，接下来就祭出可视化工具了 swagger-ui 。如果只是尝鲜，可以先用 swagger-editor 预览一下。

话不多说： swagger-ui的docker镜像版：自带nginx。

直接上docker-compose配置文件，语法可能不兼容各个版本，请自行调试。

version: "2"
services:
  swagger_ui:
    environment:
    - SWAGGER_JSON=/usr/share/nginx/html/docs/swagger.json
    image:   "swaggerapi/swagger-ui"
    volumes: ["./docs/:/usr/share/nginx/html/docs:rw"]
    restart: always
    ports:   ["9000:8080"]

把容器运行起来后，你就可以在配置的端口访问到 swagger-ui 的界面了，在顶部的搜索栏中输入想要查看的文档的URL，就可以方便的查看文档了。