安装 Swagger


全局安装 swag CLI

1. swag

复制代码

是 Swagger 的命令行工具，用于生成 API 文档。可以通过以下命令全局安装：

1. go get github.com/swaggo/swag/cmd/swag@latest
   
2. go install github.com/swaggo/swag/cmd/swag@latest

复制代码

项目依赖安装

在项目中需要安装以下依赖以支持 Gin 和 Swagger 的集成：

1. go get github.com/swaggo/gin-swagger
   
2. go get github.com/swaggo/files
   
3. go get github.com/alecthomas/template

复制代码

格式化 Swagger 注释

使用

1. swag fmt

复制代码

命令可以格式化项目中的 Swagger 注释，确保注释符合规范：

1. swag fmt

复制代码

使用 swag CLI 生成文档

运行以下命令生成 Swagger 文档（默认生成

1. docs.go

复制代码

、

1. swagger.json

复制代码

和

1. swagger.yaml

复制代码

文件）：

1. swag init

复制代码

swag init 常用选项

选项说明默认值--generalInfo, -g指定包含通用 API 信息的 Go 文件路径main.go--dir, -d指定解析的目录./--exclude排除解析的目录（多个目录用逗号分隔）空--propertyStrategy, -p结构体字段命名规则（snakecase、camelcase、pascalcase）camelcase--output, -o输出文件目录（swagger.json、swagger.yaml 和 docs.go）./docs--parseVendor是否解析 vendor 目录中的 Go 文件否--parseDependency是否解析依赖目录中的 Go 文件否--parseInternal是否解析 internal 包中的 Go 文件否--instanceName设置文档实例名称swagger示例：

1. swag init --dir ./ --output ./docs --propertyStrategy snakecase

复制代码

Swagger 注释格式

Swagger 使用声明式注释来定义 API 的元信息。以下是常用注释及其说明：

通用 API 信息

通常在

1. main.go

复制代码

中定义，用于描述整个 API 的基本信息：

1. // @title Swagger Example API
   
2. // @version 1.0
   
3. // @description This is a sample server celler server.
   
4. // @termsOfService http://swagger.io/terms/
   
5. // @contact.name API Support
   
6. // @contact.url http://www.swagger.io/support
   
7. // @contact.email support@swagger.io
   
8. // @license.name Apache 2.0
   
9. // @license.url http://www.apache.org/licenses/LICENSE-2.0.html
   
10. // @host localhost:8080
    
11. // @BasePath /api/v1
    
12. // @schemes http https

复制代码

API 路由注释

在具体路由处理函数上方添加注释，定义该接口的行为：

1. // GetPostById
   
2. // @Summary 获取文章信息
   
3. // @Produce json
   
4. // @Param id path string true "文章ID"
   
5. // @Success 200 {object} Post "成功返回文章信息"
   
6. // @Failure 400 {string} string "请求参数错误"
   
7. // @Router /post/{id} [get]
   
8. func GetPostById(c *gin.Context) {
   
9.     // 函数实现
   
10. }

复制代码

• 1. @Summary

  复制代码
  ：接口简述
  
• 1. @Produce

  复制代码
  ：返回的 MIME 类型
  
• 1. @Param

  复制代码
  ：参数定义（格式：
  1. 名称 位置 类型 是否必填 描述

  复制代码
  ）
  
• 1. @Success

  复制代码
  ：成功响应（格式：
  1. 状态码 {类型} 数据结构 描述

  复制代码
  ）
  
• 1. @Failure

  复制代码
  ：失败响应
  
• 1. @Router

  复制代码
  ：路由路径和方法
  

示例项目代码

以下是一个完整的示例，展示如何在 Gin 项目中集成 Swagger：

1. package main
   
2. 
   
3. import (
   
4.         "github.com/gin-gonic/gin"
   
5.         swaggerFiles "github.com/swaggo/files"
   
6.         ginSwagger "github.com/swaggo/gin-swagger"
   
7.         "strconv"
   
8.         _ "swagger/docs" // 导入生成的 Swagger 文档
   
9. )
   
10. 
    
11. // Post 文章结构体
    
12. type Post struct {
    
13.         ID          int64  `json:"id"`
    
14.         Title       string `json:"title"`
    
15.         Content     string `json:"content"`
    
16.         Description string `json:"description"`
    
17. }
    
18. 
    
19. func main() {
    
20.         r := gin.Default()
    
21.         r.GET("/post/:id", GetPostById)
    
22.         // 配置 Swagger 路由
    
23.         r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
    
24.         r.Run(":8080")
    
25. }
    
26. 
    
27. // GetPostById 获取文章信息
    
28. // @Summary 获取文章信息
    
29. // @Produce json
    
30. // @Param id path string true "文章ID"
    
31. // @Success 200 {object} Post "成功返回文章信息"
    
32. // @Failure 400 {string} string "请求参数错误"
    
33. // @Router /post/{id} [get]
    
34. func GetPostById(c *gin.Context) {
    
35.         id, err := strconv.ParseInt(c.Param("id"), 10, 64)
    
36.         if err != nil {
    
37.                 c.String(400, err.Error())
    
38.                 return
    
39.         }
    
40.         c.JSON(200, Post{
    
41.                 ID:          id,
    
42.                 Title:       "codepzj",
    
43.                 Content:     "测试",
    
44.                 Description: "测试",
    
45.         })
    
46. }

复制代码

生成并访问文档

运行

1. swag init

复制代码

生成文档。
启动项目：

1. go run main.go

复制代码

。
在浏览器中访问

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

复制代码

，即可查看交互式 API 文档。

总结

通过

1. swag

复制代码

和

1. gin-swagger

复制代码

，我们可以轻松为 Go 项目生成规范的 API 文档。只需要编写简单的注释，Swagger 就能自动生成交互式的文档页面，方便开发和调试。
到此这篇关于Go语言Swagger实现为项目生成 API 文档的文章就介绍到这了,更多相关Go Swagger生成API内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！

来源：互联网
免责声明：如果侵犯了您的权益，请联系站长（1277306191@qq.com），我们会及时删除侵权内容，谢谢合作！