什么是swagger
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful Web 服务。它使用 YAML 或 JSON 格式来定义 API 的结构，包括请求、响应、参数等信息。Swagger 的主要特点包括：
- 规范性：Swagger 定义了一套 API 描述的标准，使得开发者可以以统一的方式描述 API。
- 自动生成文档：Swagger 可以自动生成 API 文档，使得开发者和用户可以快速了解 API 的使用方法。
- 交互式文档：Swagger 提供了一个交互式的用户界面，用户可以直接在文档中尝试 API 调用。
- 代码生成：Swagger 可以根据 API 描述自动生成服务器和客户端的代码，节省开发时间。
- 社区支持：Swagger 有广泛的社区支持，许多开发者和公司都在使用它来构建和管理他们的 API。
- 工具链集成：Swagger 可以与许多开发工具和平台集成，如 Spring Boot、.NET Core、Node.js 等。
- 版本控制：Swagger 支持 API 的版本控制，使得 API 的迭代更加灵活。
Swagger 现在通常与 OpenAPI Specification (OAS) 结合使用，后者是一个由 Linux 基金会支持的开放标准，用于描述 API。Swagger 的工具和生态系统现在也支持 OAS。
swagger安装
$ go get -u github.com/swaggo/swag/cmd/swag # 1.16 及以上版本 $ go install github.com/swaggo/swag/cmd/swag@latest
gin-swagger
安装
go get -u github.com/swaggo/gin-swagger
使用
想要使用gin-swagger为你的代码自动生成接口文档，一般需要下面三个步骤：
- 按照swagger要求给接口代码添加声明式注释，具体参照声明式注释格式。
- 使用swag工具扫描代码自动生成API接口文档数据
- 使用gin-swagger渲染在线接口文档页面
添加注释
在程序入口main函数上以注释的方式写下项目相关介绍信息。
package main
// @title 这里写标题
// @version 1.0
// @description 这里写描述信息
// @termsOfService http://swagger.io/terms/
// @contact.name 这里写联系人信息
// @contact.url http://www.swagger.io/support
// @contact.email support@swagger.io
// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html
// @host 这里写接口服务的host
// @BasePath 这里写base path
func main() {
r := gin.New()
// liwenzhou.com ...
r.Run()
}
在你代码中处理请求的接口函数（通常位于controller层）按如下方式写上注释：
// GetCommunityHandler 获取社区列表
// @Summary 获取社区列表
// @Description 获取社区列表
// @Tags 社区列表
// @Accept json
// @Produce json
// @Param Authorization header string true "Bearer 用户令牌"
// @Success 200 {object} models.GetCommunityListParams "成功"
// @Router /community [get]
// @Request Body models.GetCommunityListParams "社区列表"
func GetCommunityHandler(c *gin.Context) {
// 获取社区列表 (Community_id, Community_name) list
list, err := communityLg.GetCommunityList()
if err != nil {
api.ResponseErrorWithMsg(c, 200, "获取社区列表失败")
return
}
api.ResponseSuccess(c, list)
}
生成接口文档数据
在项目根目录中运行命令：swag init，将会解析注解并生成所需的文件（doc文件夹和docs.go,swagger.json,swagger.yaml）
swag init
执行完命令后，会生成以下文件
./docs ├── docs.go ├── swagger.json └── swagger.yaml
然后在项目代码中注册路由的地方按如下方式引入gin-swagger相关内容：
import ( _ "project/docs" // 千万不要忘了导入把你上一步生成的docs gs "github.com/swaggo/gin-swagger" "github.com/swaggo/gin-swagger/swaggerFiles" "github.com/gin-gonic/gin" )
注册swagger api相关路由
r.GET("/swagger/*any", gs.WrapHandler(swaggerFiles.Handler))
项目程序运行起来，打开浏览器访问http://localhost:8080/swagger/index.html就能看到Swagger Api文档了。
gin-swagger同时还提供了DisablingWrapHandler函数，方便我们通过设置某些环境变量来禁用Swagger。例如：
r.GET("/swagger/*any", gs.DisablingWrapHandler(swaggerFiles.Handler, "NAME_OF_ENV_VARIABLE"))
可能遇到的问题
在我使用时发现在执行swag init时，会出现找不到gorm.Model的情况。
解决方案：
在命令行加上 --parseDependency --parseInternal
swag init --parseDependency --parseInternal
