引入swagger

swagger简介

Swagger 是一个用于描述和文档化 RESTful API 的开源工具。它使用 JSON 或 YAML 格式定义 API 的接口信息，包括请求和响应的参数、路径、方法等。Swagger 还提供了一个交互式的 UI,允许开发人员测试和调试 API。以下是 Swagger 的一些主要特点：

描述性 API 文档：Swagger 可以自动生成 API 文档，并提供详细的描述，包括请求和响应的参数、错误码、示例等信息。
交互式 UI:Swagger 提供了一个交互式的 UI,允许开发人员测试和调试 API。
代码生成器：Swagger 可以生成各种语言的客户端 SDK,方便开发人员使用 API。
授权和认证：Swagger 支持多种授权和认证方式，包括基于令牌的身份验证、OAuth2 等。
可扩展性：Swagger 可以与其他工具集成，例如 Spring Boot、Jersey、Apache CXF 等，以支持更多的功能和场景。

引入swagger

go get -u github.com/swaggo/swag/cmd/swag

对于1.17以上版本的go用户，推荐使用go install代替go get

go install github.com/swaggo/swag/cmd/swag@latest

使用swagger

在你的go文件根目录运行swag init。Swag会解析注释并生成所需的文件。如果在项目根路径出现dosc文件夹，说明初始化项目成功。

在router文件夹下的app.go中引入swagger相关工具包：

go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/files

package router

import (
   "ginchat/docs"
   "ginchat/service"
   "github.com/gin-gonic/gin"
   swaggerfiles "github.com/swaggo/files"
   ginSwagger "github.com/swaggo/gin-swagger"
)

func Router() *gin.Engine {
   r := gin.Default()
   docs.SwaggerInfo.BasePath = ""
   r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerfiles.Handler))

   r.GET("/index", service.GetIndex)
   r.GET("/user/getUserList", service.GetUserList)
   return r
}

接下来，我们需要为我们的service中的方法添加能被swagger识别的注解，用来生成我们所需要的接口文档。这里我们以GetIndex为示例

package service

import "github.com/gin-gonic/gin"

// GetIndex
// @Tags 首页
// @Success 200 {string} Welcome
// @Router /index [get]
func GetIndex(c *gin.Context) {
   c.JSON(200, gin.H{
      "message": "Welcome !!",
   })
}

这四行注解的含义分别是，函数名，接口所属模块，成功响应示例，路由地址。在终端输入swag init初始化文档，完成后，我们运行main.go文件，运行成功后，在浏览器中输入地址：

http://localhost:8080/swagger/index.html

出现以下页面，则表示成功生成文档：

测试我们的index接口是否正确，点开/index接口，右上角点击try it out。然后点击execute即可发起请求

出现以下页面，即为成功。

从零开始的IM聊天系统(三)——接口测试

引入swagger

swagger简介

引入swagger

使用swagger