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

ClamorousKun · · 3733 次点击 · · 开始浏览    
这是一个创建于 的文章,其中的信息可能已经有所发展或是发生改变。

你是否也被没有文档的项目折磨?你是否也因为项目需要写文档而头疼?你是否也被年久失修的文档坑害?少年,吃下我这发安利吧!通过部署 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 规范


有疑问加站长微信联系(非本文作者)

本文来自:掘金

感谢作者:ClamorousKun

查看原文:利用swagger打造高可用项目文档——GO篇

入群交流(和以上内容无关):加入Go大咖交流群,或添加微信:liuxiaoyan-s 备注:入群;或加QQ群:692541889

3733 次点击  
加入收藏 微博
暂无回复
添加一条新回复 (您需要 登录 后才能回复 没有账号 ?)
  • 请尽量让自己的回复能够对别人有帮助
  • 支持 Markdown 格式, **粗体**、~~删除线~~、`单行代码`
  • 支持 @ 本站用户;支持表情(输入 : 提示),见 Emoji cheat sheet
  • 图片支持拖拽、截图粘贴等方式上传