使用swagger生成接口文档

最新推荐文章于 2025-03-31 15:45:03 发布

三里清风_

最新推荐文章于 2025-03-31 15:45:03 发布

阅读量1.4k

点赞数 23

文章标签： golang

本文链接：https://blog.youkuaiyun.com/qq_63730529/article/details/136597158

版权

本文介绍了如何在gin框架中利用gin-swagger生成自动化的接口文档，通过声明式注释简化了文档编写，并展示了从安装swag工具到生成和渲染文档的详细步骤。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

使用swagger生成接口文档

有时候一份清晰明了的接口文档能够极大地提高前后端双方的沟通效率和开发效率。本文将介绍如何使用swagger生成接口文档。

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渲染在线接口文档页面

使用以下命令安装swag工具

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

第一步：添加注释

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

package main

// @title 这里写标题
// @version 1.0
// @description 这里写描述信息
// @termsOfService http://swagger.io/terms/

// @contact.name 这里写联系人信息
// @contact.url http://www.swagger.io/support
// @contact.email support@swagger.io

// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html

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