开发者

Golang使用Swag搭建api文档的全过程

目录
  • 1. 简介
  • 2. 生成swagger.json文档
    • 2.1. 安装swag
    • 2.2. 新建示例项目
    • 2.3. 新建main.go文件并输入示例代码
    • 2.4. 生成swagger.json文档
    • 2.5. 访问api文档
  • 3. 常见问题
    • 3.1. Error parsing type definition报错如何解决?
    • 3.2. 如何编写api注释?
  • 4. 将swagger.json文档转换为word文档
    • 5. 参考资料

      1. 简介

      Gwww.devze.comingolang目前最为常用的Web框架之一。

      公司项目验收需要API接口设计说明书编程Golang后端服务基于Gin框架编写),编写任务自然就落到了我们研发人员身上。

      项目经理提供了文档模板,让我们参考模板来手动编写,要求两天内完成,时间紧任务重。

      看了下文档中API接口设计内容,很简单,但是接口数量太多还需要调整文档格式,手动编写两天肯定搞不定。

      发现API接口设计内容和swagger文档格式很相近,那能不能使用工具生成swagger文档后再转换为word格式呢?

      和项目经理沟通了我的想法,项目经理回答说,内KSRDbavm容丰富、格式统一就行,不要求完全参考模板中的格式来。

      既然这样,那就开干吧!

      2. 生成swagger.json文档

      本章节仅为演示操作步骤,编写得很简洁。

      2.1. 安装swag

      首先需要安装swag命令行工具:go install github.com/swaggo/swag/cmd/swag@latest

      2.2. 新建示例项目

      比如新建swagdoc项目:go mod init swagedoc

      2.3. 新建main.go文件并输入示例代码

      package main
      
      import (
          "net/http"
      
          "swagdoc/docs"
      
          "github.com/gin-gonic/gin"
          swaggerfiles "github.com/swaggo/files"
          ginSwagger "github.com/swaggo/gin-swagger"
      )
      
      // @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")
      }
      
      func main() {
          r := gin.Default()
          docs.SwaggerInfo.BasePath = "/api/v1"
          v1 := r.Group("/api/v1")
          {
              eg := v1.Group("/example")
              {
                  eg.GET("/helloworld", Helloworld)
              }
          }
          r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerfiles.Handler))
          r.Run(":8080")
      }
      

      2.4. 生成swagger.json文档

      执行命令swagger init命令生成swagger.json编程客栈档。文件目录结构如下图所示:

      Golang使用Swag搭建api文档的全过程

      2.5. 访问api文档

      执行下列命令运行示例程序:

      go mod tidy
      go run ./main.go
      

      在浏览器中访问api文档 :

      Golang使用Swag搭建api文档的全过程

      可以通过浏览器直接访问api:

      Golang使用Swag搭建api文档的全过程

      Golang使用Swag搭建api文档的全过程

      3. 常见问题

      3.1. Error parsing type definition报错如何解决?

      若出现解析类型定义的错误,需要在执行swage init时加上对应的选项:

      Golang使用Swag搭建api文档的全过程

      例如:swag init --parseDependency --parseInternal

      3.2. 如何编写api注释?

      参考 声明式注释格式。

      4. 将swagger.json文档转换为word文档

      可以使用 swagger转word文档在线工具 来进行转换。

      如果在线工具不能使用,可以自行参考网上教程在本地搭建转换工具来进行转换,就不在此赘述了。

      转换后的word文档效果图如下所示:

      Golang使用Swag搭建api文档的全过程

      5. 参考资料

      如何使用Swag将Go的注释转换为Swagger文档?

      源码示例

      以上就是Golang使用Swag搭建api文档的全过程的详细内容,更多关于Golang Swag搭建ajavascriptpi文档的资料请关注编程客栈(www.devze.com)其它相关文章!

      0

      上一篇:

      下一篇:

      精彩评论

      暂无评论...
      验证码 换一张
      取 消

      最新开发

      开发排行榜