Gin使用swagger生成接口文档

约 1112 字大约 4 分钟

2024-09-05

什么是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

详细可以在这里查看

原文链接: https://juejin.cn/post/7377798028462096384

文章标签

后端开发程序员