SwaggerUI初探

一、SwaggerUI介绍

SwaggerUI是我们小组在做课程作业，前后端交互需要API文档时，我无意间发现的一个工具。借助SwaggerUI，我们可以便捷的获得类似下方的可视化图形界面：
SwaggerUI初探
之后，我们便可以根据此“API文档”进行开发。

“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认证的相关信息
SwaggerUI初探

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文件夹到我们的项目文件下。
SwaggerUI初探
其中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初探

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

参考链接：
https://www.ribice.ba/serving-swaggerui-golang/
https://www.ribice.ba/swagger-golang/