go-swagger简单使用

• 官网地址

  https://goswagger.io/
  

• 安装go-swagger

  go get -u github.com/go-swagger/go-swagger/cmd/swagger
  swagger version  
  

• 命令行工具
  格式：swagger [OPTIONS] < command >。swagger -h查看 swagger 使用帮助

  swagger generate spec -o swagger.yaml
  swagger serve --no-open -F=swagger --port 36666 swagger.yaml
  
  -o：指定要输出的文件名。swagger 会根据文件名后缀.yaml 或者.json，决定生成的文件格式为 YAML 或 JSON。
  –no-open：因为是在 Linux 服务器下执行命令，没有安装浏览器，所以使–no-open 禁止调用浏览器打开 URL。
  -F：指定文档的风格，可选 swagger 和 redoc。我选用了 redoc，因为觉得 redoc 格式更加易读和清晰。
  –port：指定启动的 HTTP 服务监听端口。
  

• 语法

  注释语法	功能
  swagger:mate	定义API接口全局基本信息
  swagger:route	定义路由信息
  swagger:operation	定义路由信息，可描述复杂的端点
  swagger:parameters	定义API请求参数
  swagger:response	定义API响应参数
  swagger:model	定义可以复用的Go数据结构
  swagger:allOf	嵌入其他Go结构体
  swagger:strfmt	定义格式化的字符串
  swagger:ignore	定义需要忽略的结构体

• 举例 docs

  // Package docs name.   --name:服务名
  //
  // Documentation of  API.    --简述API服务
  //
  //     Schemes: http, https  
  //     BasePath: /
  //     Version: 0.1.0
  //     Host: 127.0.0.1
  //
  //     Consumes:
  //     - application/json
  //
  //     Produces:
  //     - application/json
  //
  //    SecurityDefinitions:    --使用jwt
  //    APIKey:
  //      type: apiKey
  //      name: Authorization
  //      in: header
  //
  //     Security:
  //     - APIKey: []
  //
  // swagger:meta
       package docs
  

• 举例 swagger:operation

  // swagger:operation POST /v1/a/b a xxx  --a:相同的在一起
  //
  // 接口描述
  //
  // ---
  // consumes:
  // - multipart/form-data
  // produces:
  // - application/json
  // parameters:
  // - name: upload
  //   in: formData
  //   description: file field.
  //   type: file
  //   required: true
  // responses:
  //   '200':
  //     description: hahahahah.
  //     schema:
  //       $ref: "#/definitions/successModel"
  //   default:
  //     description: error info.
  //     schema:
  //       $ref: "#/definitions/errorModel"
  

• 举例 swagger:route

  // swagger:route POST /v1/login login loginRequest --loginReques:id,用来绑定请求内容
  // 登录.
  // responses:
  //    200: loginRequest
  //    default:errRequest
  
  // swagger:parameters loginRequest	--loginRequest：上面说的绑定请求内容
  type loginRequestWrapper struct {
  	// in:body
  	Body login.LoginRequest
  }
  
  // swagger:response loginRequest
  type getUserResponseWrapperLogin struct {
  	// in:body
  	Body login.LoginResponse
  }
  
  // 这里可以写一些下面返回的描述
  // swagger:response errRequest
  type errResponseWrapperLogin struct {
  	// in:body
  	Body struct {
  		// Error code.
  		Code int `json:"code"`
  
  		// Error message.
  		Message string `json:"message"`
  	}
  }