Go语言使用swagger生成接口文档的方法-创新互联

swagger介绍

Swagger本质上是一种用于描述使用JSON表示的RESTful API的接口描述语言。Swagger与一组开源软件工具一起使用，以设计、构建、记录和使用RESTful Web服务。Swagger包括自动文档，代码生成和测试用例生成。

在前后端分离的项目开发过程中，如果后端同学能够提供一份清晰明了的接口文档，那么就能极大地提高大家的沟通效率和开发效率。可是编写接口文档历来都是令人头痛的，而且后续接口文档的维护也十分耗费精力。

最好是有一种方案能够既满足我们输出文档的需要又能随代码的变更自动更新，而Swagger正是那种能帮我们解决接口文档问题的工具。

这里以gin框架为例，使用gin-swagger库以使用Swagger 2.0自动生成RESTful API文档。

gin-swagger实战

想要使用gin-swagger为你的代码自动生成接口文档，一般需要下面三个步骤：

• 按照swagger要求给接口代码添加声明式注释，具体参照声明式注释格式。
• 使用swag工具扫描代码自动生成API接口文档数据
• 使用gin-swagger渲染在线接口文档页面

第一步：添加注释

在程序入口main函数上以注释的方式写下项目相关介绍信息。

package main

// @title 这里写标题
// @version 1.0
// @description 这里写描述信息
// @termsOfService /tupian/20230522/

// @contact.name 这里写联系人信息
// @contact.url /tupian/20230522/
// @contact.email support@swagger.io

// @license.name Apache 2.0
// @license.url /tupian/20230522/LICENSE-2.0.html

// @host 这里写接口服务的host
// @BasePath 这里写base path
func main() {
 r := gin.New()

 // liwenzhou.com ...

 r.Run()
}