安装 Swagger
全局安装 swag CLI
是 Swagger 的命令行工具,用于生成 API 文档。可以通过以下命令全局安装:- go get github.com/swaggo/swag/cmd/swag@latest
- go install github.com/swaggo/swag/cmd/swag@latest
复制代码 项目依赖安装
在项目中需要安装以下依赖以支持 Gin 和 Swagger 的集成:- go get github.com/swaggo/gin-swagger
- go get github.com/swaggo/files
- go get github.com/alecthomas/template
复制代码 格式化 Swagger 注释
使用命令可以格式化项目中的 Swagger 注释,确保注释符合规范:使用 swag CLI 生成文档
运行以下命令生成 Swagger 文档(默认生成、和文件):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示例:- swag init --dir ./ --output ./docs --propertyStrategy snakecase
复制代码 Swagger 注释格式
Swagger 使用声明式注释来定义 API 的元信息。以下是常用注释及其说明:
通用 API 信息
通常在中定义,用于描述整个 API 的基本信息:- // @title Swagger Example API
- // @version 1.0
- // @description This is a sample server celler server.
- // @termsOfService http://swagger.io/terms/
- // @contact.name API Support
- // @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 localhost:8080
- // @BasePath /api/v1
- // @schemes http https
复制代码 API 路由注释
在具体路由处理函数上方添加注释,定义该接口的行为:- // GetPostById
- // @Summary 获取文章信息
- // @Produce json
- // @Param id path string true "文章ID"
- // @Success 200 {object} Post "成功返回文章信息"
- // @Failure 400 {string} string "请求参数错误"
- // @Router /post/{id} [get]
- func GetPostById(c *gin.Context) {
- // 函数实现
- }
复制代码
- :接口简述
- :返回的 MIME 类型
- :参数定义(格式:)
- :成功响应(格式:)
- :失败响应
- :路由路径和方法
示例项目代码
以下是一个完整的示例,展示如何在 Gin 项目中集成 Swagger:- package main
- import (
- "github.com/gin-gonic/gin"
- swaggerFiles "github.com/swaggo/files"
- ginSwagger "github.com/swaggo/gin-swagger"
- "strconv"
- _ "swagger/docs" // 导入生成的 Swagger 文档
- )
- // Post 文章结构体
- type Post struct {
- ID int64 `json:"id"`
- Title string `json:"title"`
- Content string `json:"content"`
- Description string `json:"description"`
- }
- func main() {
- r := gin.Default()
- r.GET("/post/:id", GetPostById)
- // 配置 Swagger 路由
- r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
- r.Run(":8080")
- }
- // GetPostById 获取文章信息
- // @Summary 获取文章信息
- // @Produce json
- // @Param id path string true "文章ID"
- // @Success 200 {object} Post "成功返回文章信息"
- // @Failure 400 {string} string "请求参数错误"
- // @Router /post/{id} [get]
- func GetPostById(c *gin.Context) {
- id, err := strconv.ParseInt(c.Param("id"), 10, 64)
- if err != nil {
- c.String(400, err.Error())
- return
- }
- c.JSON(200, Post{
- ID: id,
- Title: "codepzj",
- Content: "测试",
- Description: "测试",
- })
- }
复制代码 生成并访问文档
运行生成文档。
启动项目:。
在浏览器中访问- http://localhost:8080/swagger/index.html
复制代码 ,即可查看交互式 API 文档。
总结
通过和,我们可以轻松为 Go 项目生成规范的 API 文档。只需要编写简单的注释,Swagger 就能自动生成交互式的文档页面,方便开发和调试。
到此这篇关于Go语言Swagger实现为项目生成 API 文档的文章就介绍到这了,更多相关Go Swagger生成API内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家!
来源:互联网
免责声明:如果侵犯了您的权益,请联系站长(1277306191@qq.com),我们会及时删除侵权内容,谢谢合作! |