使用go-swagger为Go工程生成自动化接口文档

文章主要介绍一些常用语法、属性及其示例，如果需要了解详细的goswagger介绍，可以访问官方文档。你可以通过在代码中增加注释，来自动生成接口文档。文档的格式支持两种：一种是json，另外一种是yaml。要想通过代码注释生成接口文档，那么你的Go工程必须放在$GOPATH/src目录下。

使用swagger:meta定义接口的全局信息

属性

标记	含义
Terms Of Service	描述使用接口服务的一些协议，比如免责等
Consumes	描述接口默认请求的mime类型值，如果有多个，每个类型占据一行。支持的MIME类型有json，yaml，xml，txt，bin，urlform，multipartform
Produces	描述接口默认响应的mime类型值，如果有多个，每个类型占据一行
Schemes	描述接口默认支持的协议类型，可能的值有http，https，ws，wss
Version	当前接口的版本
Host	接口服务所在的域名
Base path	接口默认的根路径
Contact	通常来说是接口文档编写者的联系方式，格式：John Dan[email protected]
License	接口文档遵循的许可证名称

示例

// Package classification testProject API.
//
// the purpose of this application is to provide an application
// that is using plain go code to define an API
//
// This should demonstrate all the possible comment annotations
// that are available to turn go code into a fully compliant swagger 2.0 spec
//
// Terms Of Service:
//
// there are no TOS at this moment, use at your own risk we take no responsibility
//
//     Schemes: http, https
//     Host: localhost
//     BasePath: /v1
//     Version: 0.0.1
//     Contact: Haojie.zhao<[email protected]>
//
//     Consumes:
//     - application/json
//     - application/xml
//
//     Produces:
//     - application/json
//     - application/xml
//
// swagger:meta
package routers

import (
	"testProject/controllers"
	"github.com/astaxie/beego"
)

func init() {
   
    beego.Router("/", &controllers.MainController{
   })
}

然后在命令行里执行swagger generate spec -o ./swagger.json，执行完成后会在你工程的根目录下生成一个swagger.json文件。这就是自动生成的接口文档，上面内容生成的对应文件为：

{
   
  "consumes": [
    "application/json",
    "application/xml"
  ],
  "produces": [
    "application/json",
    "application/xml"
  ],
  "schemes": [
    "http",
    "https"
  ],
  "swagger": "2.0",
  "info": {
   
    "description": "the purpose of this application is to provide an application\nthat is using plain go code to define an API\n\nThis should demonstrate all the possible comment annotations\nthat are available to turn go code into a fully compliant swagger 2.0 spec",
    "title": "testProject API.",
    "termsOfService": "there are no TOS at this moment, use at your own risk we take no responsibility",
    "contact": {
   
      "name": "John Dan",
      "email": "[email protected]"
    },
    "version": "0.0.1"
  },
  "host": "localhost",
  "basePath": "/v1",
  "paths": {
   }
}

你可以在swagger Editor中查看接口文档，它会有一定样式，便于阅读。上面生成的接口文档如下图所示：

使用swagger:route定义路由信息

swagger:route标记用来定义接口的路由信息，它会将路径连接到方法，此操作获取唯一id，该id在各个位置用作方法名称。语法如下：swagger:route [method] [path pattern] [?tag1 tag2 tag3] [operation id]。

属性

标记	含义
Consumes	描述接口支持的特定的mime类型值，如果有多个，每个类型占据一行。支持的MIME类型有json，yaml，xml，txt，bin，urlform，multipartform
Produces	描述接口支持的特定的mime类型值，如果有多个，每个类型占据一行
Schemes	描述接口支持的特定协议类型，可能的值有http，https，ws，wss
Responses	响应状态码字典

示例

package controllers

import (
	"github.com/astaxie/beego"
)

type MainController struct {
   
	beego.Controller
}

// Get serves the API for this get index page
func (c *MainController) Get() {
   
	// swagger:route GET / users indexPage
	//
	// Show index page.
	//
	// This will show all available users by default.
	//
	//     Consumes:
	//     - application/json
	//
	//     Produces:
	//     - application/json
	//
	//     Schemes: http, https, ws, wss
	//
	//     Responses:
	//       default: Resp
	//	     422: validationError
	c.Data["Website"] = "beego.me"
	c.Data["Email"] = "[email protected]"
	c.TplName = "index.tpl"
}

使用swagger:response定义响应

使用swagger:route可以定义响应的名称，接着需要做的就是将这些响应名称和具体的响应结果对应起来。用法：swagger:response [?response name]。语法中的response name就是你在定义swagger:route的时候，通过Response属性设置的名字。

示例

package models
// A Resp is an response that is used when the request returned.
// swagger:response Resp
type Resp struct {
   
	// The response information
	// in: body
	//
	Body struct{
   
		// Required: true
		Status