Golang使用swaggo自动生成Restful API文档

最新推荐文章于 2024-06-22 20:09:02 发布

程序员khaos

最新推荐文章于 2024-06-22 20:09:02 发布

阅读量1k

点赞数

分类专栏： golang 文章标签： golang

本文链接：https://blog.csdn.net/A_Khaos/article/details/120690692

版权

本文介绍了如何使用Swaggo在Golang项目中自动生成RESTful API文档，避免手动编写，提高效率。Swaggo是Swagger的替代方案，允许通过代码注释生成文档。文章详细讲解了安装、在main.go中添加注释、在Handle函数上添加注释、生成和测试文档，以及如何优化生成的文档，以便在项目部署时减小二进制包的大小。

摘要由CSDN通过智能技术生成

#关于Swaggo

相信很多程序猿和我一样不喜欢写API文档。写代码多舒服，写文档不仅要花费大量的时间，有时候还不能做到面面具全。但API文档是必不可少的，相信其重要性就不用我说了，一份含糊的文档甚至能让前后端人员打起来。而今天这篇博客介绍的swaggo就是让你只需要专注于代码就可以生成完美API文档的工具。废话说的有点多，我们直接看文章。

或许你使用过Swagger, 而 swaggo就是代替了你手动编写yaml的部分。只要通过一个命令就可以将注释转换成文档，这让我们可以更加专注于代码。

目前swaggo主要实现了swagger 2.0 的以下部分功能：

基本结构（Basic Structure）
API 地址与基本路径（API Host and Base Path）
路径与操作（Paths and Operations）
参数描述（Describing Parameters）
请求参数描述（Describing Request Body）
返回描述（Describing Responses）
MIME 类型（MIME Types）
认证（Authentication）
Basic Authentication
API Keys
添加实例（Adding Examples）
文件上传（File Upload）
枚举（Enums）
按标签分组（Grouping Operations With Tags）
扩展（Swagger Extensions）

下文内容均以gin-swaggo为例

这里是demo地址

2020/05/16 更新：

swag 升级到了 v1.6.5，返回数据格式有更新。

最新的请关注官网文档。

本文最后，优化部分可以了解一下。

#使用使用

#安装swag-cli-及下载相关包安装`swag cli` 及下载相关包

要使用swaggo,首先需要安装swag cli。

    go get -u github.com/swaggo/swag/cmd/swag

然后我们还需要两个包。

    # gin-swagger 中间件
    go get github.com/swaggo/gin-swagger
    # swagger 内置文件
    go get github.com/swaggo/gin-swagger/swaggerFiles

可以看一下自己安装的版本

    swag --version
    swag version v1.6.5

#在main-go内添加注释在`main.go`内添加注释

    package main
    
    import (
    "github.com/gin-gonic/gin"
    	ginSwagger "github.com/swaggo/gin-swagger"
    "github.com/swaggo/gin-swagger/swaggerFiles"
    )
    
    // @title Swagger Example API
    // @version 1.0
    // @description This is a sample server celler server.
    // @termsOfService https://razeen.me
    
    // @contact.name Razeen
    // @conta