【gin】【swag】

@

目录

写在前面

  • 相关博文
  • 个人博客首页
  • 免责声明：仅供学习交流使用！开源框架可能存在的风险和相关后果将完全由用户自行承担，本人不承担任何法律责任。

gin swagger

安装依赖

go install github.com/swaggo/swag/cmd/swag@latest
go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/files

添加注释

// @BasePath /api/v1

// PingExample godoc
// @Summary ping example
// @Schemes
// @Description do ping
// @Tags example
// @Accept json
// @Produce json
// @Success 200 {string} Helloworld
// @Router /example/helloworld [get]
func Helloworld(g *gin.Context)  {
	g.JSON(http.StatusOK,"helloworld")
}

生成 api 文件

swag init

路由设置

package main

import (
   "github.com/gin-gonic/gin"
   docs "github.com/your-self-go-project-name/docs" // 注意这个 docs 目录需要填写你自己项目的真实路径
   swaggerfiles "github.com/swaggo/files"
   ginSwagger "github.com/swaggo/gin-swagger"
   "net/http"
)

func main()  {
   r := gin.Default()
   docs.SwaggerInfo.BasePath = "/api/v1" // api 文件路径
   v1 := r.Group("/api/v1")
   {
      eg := v1.Group("/example")
      {
         eg.GET("/helloworld",Helloworld)
      }
   }
   r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerfiles.Handler))
   r.Run(":8080")

}

注释

编写注释

在Gin的路由处理器函数上方，编写符合Swag规范的注释。以下是注释的基本组成部分：

// @Summary 摘要说明
// @Description 详细描述
// @Tags 标签
// @Accept 输入格式
// @Produce 返回格式
// @Param 参数名 参数位置 参数类型 是否必须 "参数描述"
// @Success 成功返回状态码 {返回类型} 返回数据结构类型 "成功返回信息描述"
// @Failure 失败返回状态码 {返回类型} 返回数据结构类型 "失败返回信息描述"
// @Router 路由 [HTTP方法]
以下将详细描述在配合Gin使用Swagger文档时你提及的特定注释。

@Description

这一行提供接口的详细描述，可以是多行，支持Markdown语法，让你的API描述更加丰富和详细。

@Tags

用于对API进行分类，这些标签在Swagger UI中会用于分组展示。比如，可能会根据资源（如users, orders）或行为(authentication, statistics)来分类。

@Accept

指定API可以处理的MIME类型，常见的有json, xml, plain, html, mpfd等。该值与请求头Content-Type相关。

@Produce

指定API能够返回的MIME类型，这通常与响应的Content-Type头信息相关。常见的值有json, xml, plain, html等。

@Param

这个注释是用来描述API接口的参数信息：

参数名(name)：参数的名称。
参数位置(in)：参数的位置，可选值有：
path：路径参数，例如/users/{id}中的id。
query：查询参数，附加在URL后面，例如/users?role=admin中的role。
header：请求头参数，如带有认证信息的Authorization字段。
body：请求体参数，通常用于POST或PUT请求中的数据。
formData：表单数据，经常用于上传文件。
参数类型(type)：参数的数据类型，如string, int, bool, []string等。
是否必须(required)：这表明参数是否为必须，取值为true或false。
参数描述(data description)：一个描述该参数的文本信息。
@Success & @Failure

这两个注释分别描述了API响应成功或失败时的返回情况：

成功或失败的HTTP状态码（如200, 400, 500）。
返回类型，一般为object（用于单个对象）、array（用于对象数组）或string（错误信息或简单文本）。
返回数据结构类型，指向定义的结构体或基本数据类型，swag会根据这些信息在文档中生成和展示模型结构。
成功或失败的信息描述，通常是操作成功或错误时的消息文本。
@Router

这个注释描述了路由信息：

路由(path): API的路径。
HTTP方法(method): 请求使用的HTTP方法，如GET, POST, PUT, DELETE等。

param

Swagger是一个工具套件，用于生成、展示和消费OpenAPI（以前称为Swagger）规范的API文档。Go语言中可以配合Gin框架使用swaggo库来自动生成API文档。

在使用gin框架，整合swaggo生成API文档时，param是一个重要的注释关键字，它用于描述API接口的参数信息。

param注释的格式如下：

// @Param 参数名 参数位置 参数类型 是否必须 "参数描述"
其中：

参数名（name）：表示参数的名称，在HTTP请求中作为键名出现。
参数位置（paramType）：表示参数的位置，可以是path（路径参数）、query（查询字符串参数）、header（HTTP头参数）、body（请求体）、formData（用于上传文件）。
参数类型（dataType）：表示参数的Go类型或者特殊类型，如string、int、bool、[]string等。
是否必须（required）：表示此参数是否必需填写，true代表必需，false代表可选。
参数描述（description）：这是对参数的描述信息，确保API的使用者能够理解。
例子：

// @Summary 添加新用户
// @Description 添加一个新用户
// @Tags users
// @Accept json
// @Produce json
// @Param name query string true "用户的姓名"
// @Param age query int false "用户的年龄"
// @Success 200 {object} User
// @Failure 400 {string} string "无法解析请求参数"
// @Router /user [post]
func addUser(c *gin.Context) { 
	// ...
}
这个API的param注释说明了有两个查询字符串参数name和age，其中name是必须的，age是可选的。

访问

http://host:port/sagger/index.html

源码分析

gin-swagger

参考资料

基础/标准库/第三方库

golang 导航

编程规范

算法｜面试

项目

posted @ 2024-05-08 16:50  Nones  阅读(25)  评论(0)  编辑  收藏  举报