• 设为首页
  • 收藏本站
  • 积分充值
  • VIP赞助
  • 手机版
  • 微博
  • 微信
    微信公众号 添加方式:
    1:搜索微信号(888888
    2:扫描左侧二维码
  • 快捷导航
    福建二哥 门户 查看主题

    Go语言Swagger实现为项目生成 API 文档

    发布者: 皮3591 | 发布时间: 2025-8-14 10:46| 查看数: 96| 评论数: 0|帖子模式

    安装 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. import (
    3.         "github.com/gin-gonic/gin"
    4.         swaggerFiles "github.com/swaggo/files"
    5.         ginSwagger "github.com/swaggo/gin-swagger"
    6.         "strconv"
    7.         _ "swagger/docs" // 导入生成的 Swagger 文档
    8. )

    9. // Post 文章结构体
    10. type Post struct {
    11.         ID          int64  `json:"id"`
    12.         Title       string `json:"title"`
    13.         Content     string `json:"content"`
    14.         Description string `json:"description"`
    15. }

    16. func main() {
    17.         r := gin.Default()
    18.         r.GET("/post/:id", GetPostById)
    19.         // 配置 Swagger 路由
    20.         r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
    21.         r.Run(":8080")
    22. }

    23. // GetPostById 获取文章信息
    24. // @Summary 获取文章信息
    25. // @Produce json
    26. // @Param id path string true "文章ID"
    27. // @Success 200 {object} Post "成功返回文章信息"
    28. // @Failure 400 {string} string "请求参数错误"
    29. // @Router /post/{id} [get]
    30. func GetPostById(c *gin.Context) {
    31.         id, err := strconv.ParseInt(c.Param("id"), 10, 64)
    32.         if err != nil {
    33.                 c.String(400, err.Error())
    34.                 return
    35.         }
    36.         c.JSON(200, Post{
    37.                 ID:          id,
    38.                 Title:       "codepzj",
    39.                 Content:     "测试",
    40.                 Description: "测试",
    41.         })
    42. }
    复制代码
    生成并访问文档

    运行
    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),我们会及时删除侵权内容,谢谢合作!

    本帖子中包含更多资源

    您需要 登录 才可以下载或查看,没有账号?立即注册

    ×

    最新评论

    QQ Archiver 手机版 小黑屋 福建二哥 ( 闽ICP备2022004717号|闽公网安备35052402000345号 )

    Powered by Discuz! X3.5 © 2001-2023

    快速回复 返回顶部 返回列表