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 http://swagger.io/terms/// @contact.name 这里写联系人信息// @contact.url http:///gin-gonic/gin")

注册swagger api相关路由

r.GET("/swagger/*any", gs.WrapHandler(swaggerFiles.Handler))

把你的项目程序运行起来，打开浏览器访问http://localhost:8080/swagger/index.html就能看到Swagger 2.0 Api文档了。

gin_swagger文档

gin-swagger同时还提供了DisablingWrapHandler函数，方便我们通过设置某些环境变量来禁用Swagger。例如：

r.GET("/swagger/*any", gs.DisablingWrapHandler(swaggerFiles.Handler, "NAME_OF_ENV_VARIABLE"))

此时如果将环境变量NAME_OF_ENV_VARIABLE设置为任意值，则/swagger/*any将返回404响应，就像未指定路由时一样。

总结

到此这篇关于Go语言使用swagger生成接口文档的文章就介绍到这了,更多相关Go使用swagger生成接口文档内容请搜索以前的文章或继续浏览下面的相关文章希望大家以后多多支持！