概述
Swagger 是一款用于生成 RESTful 风格 API 接口文档的框架。目前被大多数框架数框架支持,笔者认为 Swagger 最大的特点就是可以让代码和文档绑定在一起,在开发接口的同时接口文档也做好了。 这比文档集中管理要方便的多,可维护性大大提升。让小伙伴更有意愿去写接口文档。
了解 Swagger 基本概念,我们开始切入主题:Gin 集成 Swagger。
安装
前提条件:已安装好 Gin
- 安装
swagger
文档生成命令行工具。
$ go get -u github.com/swaggo/swag/cmd/swag
生成文档:
$ swag init
- 安装
gin-swagger
$ go get -u github.com/swaggo/gin-swagger
$ go get -u github.com/swaggo/files
Demo
安装好之后就可以开始啦,为了方便演示,笔者整理了简单Demo。
main.go
package main
import (
"gin-swag/controllers"
"github.com/gin-gonic/gin"
gs "github.com/swaggo/gin-swagger"
"github.com/swaggo/gin-swagger/swaggerFiles"
)
// @title Book 接口文档
// @version 1.0
// @description Book 接口文档
// @contact.name roy
// @contact.email roy@mango.im
func main() {
r := gin.Default()
// 路由
r.GET("/books", controllers.FindBooks)
r.GET("/books/:id", controllers.FindBook)
r.POST("/books", controllers.CreateBook)
r.PATCH("/books/:id", controllers.UpdateBook)
r.DELETE("/books/:id", controllers.DeleteBook)
r.GET("/swagger/*any", gs.WrapHandler(swaggerFiles.Handler))
r.Run()
}
controllers/book.go
package controllers
import (
_ "gin-swag/docs"
"github.com/gin-gonic/gin"
"net/http"
)
type BookInput struct {
Title string `json:"title" binding:"required"`
Author string `json:"author" binding:"required"`
}
// FindBooks 获取书列表
// @Summary 获取书列表
// @Description 获取书列表
// @Tags 书
// @Accept application/json
// @Produce application/json
// @Success 200
// @Router /books [get]
func FindBooks(c *gin.Context) {
// todo 具体逻辑
c.JSON(http.StatusOK, gin.H{"data": nil})
}
// FindBook 获取单本书
// @Summary 获取单本书
// @Description 获取单本书
// @Tags 书
// @Accept application/json
// @Produce application/json
// @Param id path int true "book id"
// @Success 200
// @Router /books/{id} [get]
func FindBook(c *gin.Context) {
// todo 具体逻辑
c.JSON(http.StatusOK, gin.H{"data": nil})
}
// CreateBook 创建书
// @Summary 创建书
// @Description 创建书
// @Tags 书
// @Accept application/json
// @Produce application/json
// @Param book body BookInput true "book"
// @Success 200
// @Router /books [post]
func CreateBook(c *gin.Context) {
// todo 具体逻辑
c.JSON(http.StatusOK, gin.H{"data": nil})
}
// UpdateBook 更新书
// @Summary 更新书
// @Description 更新书
// @Tags 书
// @Accept application/json
// @Produce application/json
// @Param id path int true "book id"
// @Param book body BookInput true "book"
// @Success 200
// @Router /books/{id} [patch]
func UpdateBook(c *gin.Context) {
// todo 具体逻辑
c.JSON(http.StatusOK, gin.H{"data": nil})
}
// DeleteBook 删除书
// @Summary 删除书
// @Description 删除书
// @Tags 书
// @Accept application/json
// @Produce application/json
// @Param id path int true "book id"
// @Success 200
// @Router /books/{id} [delete]
func DeleteBook(c *gin.Context) {
// todo 具体逻辑
c.JSON(http.StatusOK, gin.H{"data": nil})
}
项目目录下运行 swag init
即可生成文档。
打开 http://localhost:8080/swagger/index.htm
参数解释
注释 | 描述 |
---|---|
description | 接口描述信息 |
id | 用于标识操作的唯一字符串。 在所有 API 操作中必须是唯一的。 |
tags | 每个 API 操作的标签列表,以逗号分隔。 |
summary | 操作的简短摘要。 |
accept | API 可以使用的 MIME 类型列表 |
produce | API 可以生成的 MIME 类型列表。 |
param | 参数用空格分隔 |
security | 每个 API 操作的安全性。 |
success | 以空格分隔的成功响应。 |
failure | 以空格分隔的失败响应。 |
router | 路由 |
其中 param 支持:
- object (struct)
- string (string)
- integer (int, uint, uint32, uint64)
- number (float32)
- boolean (bool)
- array
更多属性定义参考官方文档:https://swaggo.github.io/swaggo.io/declarative_comments_format/api_operation.html