【go语言开发】swagger安装和使用

Myth丶恋晨 2024-05-24 05:39 91阅读 0赞

> 本文主要介绍go-swagger的安装和使用，首先介绍如何安装swagger，测试是否成功；然后列出常用的注释和给出使用例子；最后生成接口文档，并在浏览器上测试

#### 文章目录 ####

*  安装
 *  注释说明
 *   *  常用注释
     *  参考例子
 *  文档生成
 *   *  格式化文档
     *  生成docs.go
     *  设置路由访问
     *  浏览器访问

## 安装 ##

命令行安装swagger最新库

go install github.com/swaggo/swag/cmd/swag@latest

其他安装文件

go get -u github.com/swaggo/gin-swagger   
    go get -u github.com/swaggo/files
    # 模版
    go get -u github.com/alecthomas/template

`swag -v`测试swagger是否安装成功：  
![在这里插入图片描述][af58b39d0b424d8cb717366cf71142e7.png]  
查看常用命令：  
![在这里插入图片描述][a0ee16c09de440309901d41d6cdb6585.png]

## 注释说明 ##

### 常用注释 ###

当使用 Go Swagger 时，可以使用不同的注释标记来描述 API 的各个方面，以便生成符合 OpenAPI 规范的 Swagger 文档。以下是常用的 Swagger 注释说明，列出了所有的注释标记：

*  **@Summary**：用于描述 API 操作的简要概述。
 *  **@Description**：用于提供对 API 操作的详细描述和说明。
 *  **@ID**：用于指定 API 操作的唯一标识符。
 *  **@Param**：用于描述 API 操作的参数，包括参数名、位置、数据类型、是否必需等信息。
 *  **@Success**：用于描述 API 操作的成功响应，包括状态码、响应数据结构等信息。
 *  **@Failure**：用于描述 API 操作的失败响应，包括状态码、响应数据结构等信息。
 *  **@Router**：用于指定 API 路由的信息，包括路径、HTTP 方法等。
 *  **@Accept**：用于指定 API 操作支持的请求内容类型。
 *  **@Produce**：用于指定 API 操作产生的响应内容类型。

### 参考例子 ###

// Register 用户注册
    //
    //	@Summary	用户注册
    //	@Produce	json
    //	@Router		/api/user/register [post]
    //	@Param		username	query	string	true	"用户名"
    //	@Param		password	query	string	true	"密码"
    //	@Param		mobile		query	string	true	"电话"
    func Register(c *gin.Context) {
        
    	userName := c.Query("username")
    	password := c.Query("password")
    	mobile := c.Query("mobile")
    	...
    }

main.go

//	@title			code-go api
    //	@version		1.0
    //	@description	code-go项目swagger api介绍
    //	@termsOfService	http://swagger.io/terms/
    
    //	@contact.name	猫哥说
    //	@contact.url	www.maogeshuo.com
    //	@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	/
    
    //	@securityDefinitions.basic	BasicAuth
    
    // @externalDocs.description	OpenAPI
    // @externalDocs.url			https://swagger.io/resources/open-api/
    func main() {
        
    ...
    }

## 文档生成 ##

### 格式化文档 ###

swag fmt

### 生成docs.go ###

swag init

![在这里插入图片描述][ffdfd49225cf449192269dee8c48ac37.png]  
执行完`swag init`，会生成圈红区域文件

![在这里插入图片描述][343224a8e526478c884d8d349ed003a4.png]

### 设置路由访问 ###

参考截图配置路由路径

norm.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

![在这里插入图片描述][a75c28b85592411c9ca7725cf06bd003.png_pic_center]

### 浏览器访问 ###

浏览器输入访问地址：http://localhost:8080/swagger/index.html

![在这里插入图片描述][4adf9047693b4dcca554381f9e639dfa.png_pic_center]  
![在这里插入图片描述][0064889028af4bafbc9c8b70ed705dd0.png_pic_center]

--------------------

欢迎大家访问个人博客网址：[https://www.maogeshuo.com][https_www.maogeshuo.com]，博主努力更新中…

[af58b39d0b424d8cb717366cf71142e7.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/05/24/720b130470a649728f33a2f44c662c67.png
[a0ee16c09de440309901d41d6cdb6585.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/05/24/b615acfd1d1b4cd98e6e0e70c96ad7e2.png
[ffdfd49225cf449192269dee8c48ac37.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/05/24/cb6170a804354d2ab9db52f8242ecb08.png
[343224a8e526478c884d8d349ed003a4.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/05/24/dbd08ce50b0942e490b89f1602fcf879.png
[a75c28b85592411c9ca7725cf06bd003.png_pic_center]: https://image.dandelioncloud.cn/pgy_files/images/2024/05/24/541c28e8545b44358cad4640f6090d0f.png
[4adf9047693b4dcca554381f9e639dfa.png_pic_center]: https://image.dandelioncloud.cn/pgy_files/images/2024/05/24/1b2372e575464051a131575f167da04c.png
[0064889028af4bafbc9c8b70ed705dd0.png_pic_center]: https://image.dandelioncloud.cn/pgy_files/images/2024/05/24/eaa31826bb2648fa8746f3a7da87a3db.png
[https_www.maogeshuo.com]: https://www.maogeshuo.com