一、SwaggerUI介绍
SwaggerUI是我们小组在做课程作业,前后端交互需要API文档时,我无意间发现的一个工具。借助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认证的相关信息
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的展示文档,还需要进一步的学习。
参考链接:
https://www.ribice.ba/serving-swaggerui-golang/
https://www.ribice.ba/swagger-golang/