SwaggerUI初探

一、SwaggerUI介绍

“Swagger UI 允许任何人（无论是你的开发团队还是最终用户）在没有任何实现逻辑的情况下对 API 资源进行可视化和交互。它（API文档）通过 Swagger 定义自动生成，可视化文档使得后端实现和客户端消费变得更加容易。” –SmartBear

源码地址在这里。

二、SwaggerUI使用

以user服务为例。

安装go-swagger

$ go get github.com/go-swagger/go-swagger/cmd/swagger 

swagger:meta

以下内容放在项目程序入口main.go中：

// Copyright 2019 money-hub. All rights reserved. // Use of this source code is governed by a MIT-style // license that can be found in the LICENSE file. // money-hub MoneyDodo/personalTasks // // This documentation describes example APIs found under https://github.com/ribice/golang-swaggerui-example // // Schemes: http // Version: 1.0.0 // License: MIT http://opensource.org/licenses/MIT // // Consumes: // - application/json // // Produces: // - application/json // // Security: // - bearer // // SecurityDefinitions: // bearer: // type: apiKey // name: Authorization // in: header // // swagger:meta 

1. money-hub MoneyDodo/personalTasks – 项目名称
2. This documentation …… – 第二行为description
3. Schemes – HTTP或HTTPS
4. Version – API版本号
5. License – 许可证
6. Consumes、Produces – 表示request和response的数据类型
7. Security – 授权按钮
8. SecurityDefinitions – 安全类型定义
点击Authorize会弹出如下提示框：其中即为JWT认证的相关信息

swagger:operation

// swagger:operation PUT /api/users/{ 
   userid} users swaggPutReq // --- // summary: Update the user profile // description: Update the user profile with the profile. Also, you need to specify the user ID. // parameters: // - name: userid // in: path // description: id of user // type: string // required: true // - name: Body // in: body // schema: // "$ref": "#/definitions/User" // required: true // responses: // "200": // "$ref": "#/responses/swaggNoReturnValue" // "400": // "$ref": "#/responses/swaggBadReq" 

1. swagger:operation – 提示符，表示一个请求操作

2. PUT – HTTP方法

3. /api/users/{userid} – 路径

4. users – 类似于路由分隔标签，将相同的分隔标签的请求归到同一组

5. swaggPutReq – 此参数没有具体意义，单参数是强制性的，但是推荐不同请求使用不同的参数。命名格式可采用swaggXXXReq，若不同请求该参数一样，会出现很多bug。

6. — – 分隔符，下方代码为YAML格式的swagger规范，缩进必须保持一致且正确，推荐使用两格缩进。否则将无法正常解析。

7. summary – 标题，API的概括描述

8. description – 描述，API的详细描述

9. parameters – URL参数，此例子中为{userId}，如果需要query的，可使用？name={name}来表示

10. – name – 指定参数，此例子中为URL中的userId

11. in – 表示此参数位于哪个部分，path表示位于URL路径中，body表示位于上传的request body中

12. description – 参数说明

13. type – 指定参数类型

14. required – 是否一定需要此参数

15. schema – 当参数位于body中需要此参数，指定参数的数据结构，”$ref”: “#/definitions/XXX”按照此种格式写即可，XXX为定义的model文件(并非swagger/model.go)中的具体的数据类型，具体原因尚未搞懂。

16. responses – 说明返回类型。

17. “200” – 200表示状态码，我用200表示成功的请求；“$ref”: “#/responses/swaggNoReturnValue”按照此格式来书写，其中swaggNoReturnValue定义在swagger/model.go文件中，使用到了swagger:response：

// HTTP status code 200 and no return value // swagger:response swaggNoReturnValue type swaggNoReturnValue struct { 
    // in:body Body struct { 
    // HTTP Status Code 200 Status bool `json:"status"` // Detailed error message Errinfo string `json:"errinfo"` } } 

• 第一行注释：尽量书写，会体现在swaggerui中
• 第二行注释：swagger:response为提示符，swaggNoReturnValue为下方数据类型的一个tag，这两者共同组成了”$ref”: “#/responses/swaggNoReturnValue”
• 数据结构中，有三个属性：Status、Errinfo、Data，上述结构中没有返回值，所以取消了最后一个参数。

18. “400” – 400表示状态码，我用400来表示失败的请求。返回格式说明与上述过程一致。

swagger:route

// swagger:route POST /api/users users swaggCreateUserReq // Create a new user with the profile. // If the user's id is "exists", error will be returned. // responses: // 200: swaggNoReturnValue // 400: swaggBadReq 

swagger:route 是简单 API 的短注释,它适用于没有输入参数（路径/查询参数）的 API，如果API存在users/{userid}或者users/search?name={name}类型的参数，则必须使用swagger:operation。
1. swagger:route – 提示符，表示一个请求操作
2. POST – HTTP方法
3. /api/users – 路径
4. users – 类似于路由分隔标签，将相同的分隔标签的请求归到同一组
5. swaggCreateUserReq – 用于请求上传的参数
参数定义在swagger/model.go文件中，使用到swagger:parameters：

// Create User request // swagger:parameters swaggCreateUserReq type swaggCreateUserReq struct { 
    // in:body Body model.User } 

• 第一行注释：描述此参数
• 第二行注释：swagger:parameters表示请求参数提示符，swaggCreateUserReq为请求的参数ID值。
• 第三行：结构体名称没有必要和swagger:parameters后的参数ID值保持一致，但推荐命名相同
• 第四行注释：in:body或者in:query表示包含此参数的位置
• 第五行为实际的内嵌结构
  6. Create a new user with the profile. – 摘要（标题），在第一个句号.之前的是标题，如果没有句号，则这些注释会被作为描述
  7. If the user’s id is “exists”…… – 描述，在第一个句号后面的为描述
  8. responses – 说明返回类型。
  9. 200: swaggNoReturnValue – 简写，表明200返回值为swaggNoReturnValue
  10. 400: swaggBadReq – 简写，表示400返回值为swaggerBadReq

  
  
  
  
  
  
  
  
  
  

【说明】swagger:parameters & swagger:response已在上述操作中详细说明，不在叙述。

三、运行SwaggerUI

从Github swagger-ui中克隆项目到本地，然后拷贝其中的dist文件夹到我们的项目文件下。

其中dist文件夹即为克隆的项目中的dist；model.go为我们定义的swagger:parameters和swagger:response所在的文件；main.go为swaggerui的服务器文件。

• 修改swagger/swaggerui/dist/index.html中的url

const ui = SwaggerUIBundle({ 
    url: "./swagger.user.json", dom_id: '#swagger-ui', …… }) 

• 定义main.go

package main import "net/http" func main() { fs := http.FileServer(http.Dir("swagger/swaggerui/dist")) http.Handle("/swaggerui/", http.StripPrefix("/swaggerui/", fs)) http.ListenAndServe(":8000", nil) } 

• 启动服务器
  在项目根目录下：go run swagger/swaggerui/main.go
  
  

四、效果图

打开浏览器localhost:8000/swaggerui/


swaggerui的动态交互并没有实现，只是将其作为API的展示文档，还需要进一步的学习。