利用swagger打造高可用项目文档——GO篇

你是否也被没有文档的项目折磨？你是否也因为项目需要写文档而头疼？你是否也被年久失修的文档坑害？少年，吃下我这发安利吧！通过部署 Swagger，这些问题都将远离你，精美、易读、可测试、时效性高的文档，不想试试么？

引言

swagger的基本概念和本人构建整个项目的基础思路，和之前的文章，利用swagger打造高可用项目文档——PHP篇中提到的一致，这里不再做赘述，这里只描述部署与使用过程中的不同点。

部署

go的基础环境安装，请参考官方文档，这里假定你已经有了一个可以稳定运行的go环境。

• 首先安装基础组件

    go get -u github.com/go-swagger/go-swagger/cmd/swagger
  复制代码

  这里建议直接使用go get进行安装，很多使用brew安装的项目，会遇到GOROOT路径无法正确读取的问题，如果遇到类似问题可以参考下面的issue

  issue

• 接口中添加注释

  注释语法可以参考官方文档使用规则

    这里提供一组简单的例子，笔者使用的是go+kit，未使用框架
    
    由于go kit提供了endpoint层，request和response由服务框架自动生成，可以方便的在上面添加注释
    
    // Package classification Example api.
    //
    // This is an example api
    //
    //      Host: 127.0.0.1
    //      Version: 1.0.0
    //
    // swagger:meta
    
    package endpoint
    
    // swagger:parameters GetExampleRequest
    type GetExampleRequest struct {
    // in: query
    Id    string `json:"id"`
    }
    
    // example api response
    // swagger:response GetExampleResponse
    type GetExampleResponse struct {
        // response body
        // in: body
        Body struct {
            // the code og response
            //
            // Required: true
            Code    int             `json:"code"`
            // the message of response
            //
            // Required: true
            Message string          `json:"message"`
            // response data
            Data    interface{}     `json:"data"`
        }
    }
    
    // swagger:route GET /example tag GetExampleRequest
    //
    // example route
    //
    // This is an example route
    //
    // Responses:
    // 200: GetExampleResponse
  复制代码

  复制该例子，便可以得到一个具有标准化注释的接口

• 获取标准 Swagger Json

  只需要在项目根目录中执行

    swagger generate spec -o ./swagger.json
  复制代码

  该命令会从项目的main.go文件开始扫描，解析所有的swagger注释 此时，便会在项目的根路径下生成一个swagger.json文件，以上面提供的注释为例，产生内容如下

    {
        "swagger": "2.0",
        "info": {
            "description": "This is an example api",
            "title": "Example api.",
            "version": "1.0.0"
        },
        "host": "127.0.0.1",
        "paths": {
            "/example": {
                "get": {
                    "description": "This is an example route",
                    "tags": [
                        "tag"
                    ],
                    "summary": "example route",
                    "operationId": "GetExampleRequest",
                    "parameters": [
                        {
                            "type": "string",
                            "x-go-name": "Id",
                            "name": "id",
                            "in": "query"
                        }
                    ],
                    "responses": {
                        "200": {
                            "$ref": "#/responses/GetExampleResponse"
                        }
                    }
                }
            }
        },
        "responses": {
            "GetExampleResponse": {
                "description": "example api response",
                "schema": {
                    "type": "object",
                    "required": [
                        "code",
                        "message"
                    ],
                    "properties": {
                        "code": {
                            "description": "the code og response",
                            "type": "integer",
                            "format": "int64",
                            "x-go-name": "Code"
                        },
                        "data": {
                            "description": "response data",
                            "type": "object",
                            "x-go-name": "Data"
                        },
                        "message": {
                            "description": "the message of response",
                            "type": "string",
                            "x-go-name": "Message"
                        }
                    }
                }
            }
        }
    }
  复制代码

  至此，一个标准的 Swagger Json数据便诞生了。 接下来的思路就很简单了，新写一个接口，将该json文件直接输出，然后利用前文利用swagger打造高可用项目文档——PHP篇中提到的chrome插件直接打开接口即可。

至此，一个快捷方便的go swagger文档便诞生了，具体使用的方式，就看大家的个人喜好了。Hope you enjoy it!

可参考文档

Go Swagger

Go Swagger官方使用文档

Swagger官网

Swagger标准的参数解释

Swagger OpenAPI 规范

有疑问加站长微信联系（非本文作者）