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 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()

 // liwenzhou.com ...

 r.Run()
}

在你代码中处理请求的接口函数(通常位于controller层)按如下方式写上注释:

// GetPostListHandler2 升级版帖子列表接口
// @Summary 升级版帖子列表接口
// @Description 可按社区按时间或分数排序查询帖子列表接口
// @Tags 帖子相关接口
// @Accept application/json
// @Produce application/json
// @Param Authorization header string false "Bearer 用户令牌"
// @Param object query models.ParamPostList false "查询参数"
// @Security ApiKeyAuth
// @Success 200 {object} _ResponsePostList
// @Router /posts2 [get]
func GetPostListHandler2(c *gin.Context) {
 // GET请求参数(query string):/api/v1/posts2?page=1&size=10&order=time
 // 初始化结构体时指定初始参数
 p := &models.ParamPostList{
 Page: 1,
 Size: 10,
 Order: models.OrderTime,
 }

 if err := c.ShouldBindQuery(p); err != nil {
 zap.L().Error("GetPostListHandler2 with invalid params", zap.Error(err))
 ResponseError(c, CodeInvalidParam)
 return
 }
 data, err := logic.GetPostListNew(p)
 // 获取数据
 if err != nil {
 zap.L().Error("logic.GetPostList() failed", zap.Error(err))
 ResponseError(c, CodeServerBusy)
 return
 }
 ResponseSuccess(c, data)
 // 返回响应
}

上面注释中参数类型使用了objectmodels.ParamPostList具体定义如下:

// bluebell/models/params.go

// ParamPostList 获取帖子列表query string参数
type ParamPostList struct {
 CommunityID int64 `json:"community_id" form:"community_id"` // 可以为空
 Page int64 `json:"page" form:"page" example:"1"` // 页码
 Size int64 `json:"size" form:"size" example:"10"` // 每页数据量
 Order string `json:"order" form:"order" example:"score"` // 排序依据
}

响应数据类型也使用的object,我个人习惯在controller层专门定义一个docs_models.go文件来存储文档中使用的响应数据model。

// bluebell/controller/docs_models.go

// _ResponsePostList 帖子列表接口响应数据
type _ResponsePostList struct {
 Code ResCode   `json:"code"` // 业务响应状态码
 Message string   `json:"message"` // 提示信息
 Data []*models.ApiPostDetail `json:"data"` // 数据
}

第二步:生成接口文档数据

编写完注释后,使用以下命令安装swag工具:

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

在项目根目录执行以下命令,使用swag工具生成接口文档数据。

swag init

执行完上述命令后,如果你写的注释格式没问题,此时你的项目根目录下会多出一个docs文件夹。

./docs
├── docs.go
├── swagger.json
└── swagger.yaml

第三步:引入gin-swagger渲染文档数据

然后在项目代码中注册路由的地方按如下方式引入gin-swagger相关内容:

import (
 // liwenzhou.com ...

 _ "bluebell/docs" // 千万不要忘了导入把你上一步生成的docs

 gs "github.com/swaggo/gin-swagger"
 "github.com/swaggo/gin-swagger/swaggerFiles"

 "github.com/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生成接口文档内容请搜索我们以前的文章或继续浏览下面的相关文章希望大家以后多多支持我们!

(0)

相关推荐

  • Django REST Swagger实现指定api参数

    为什么要指定swagger的api参数 api的参数有多种类型: query 参数,如 /users?role=admin path 参数,如 /users/{id} header 参数,如 X-MyHeader: Value body 参数,描述POST,PUT,PATCH请求的body form 参数,描述 Content-Type of application/x-www-form-urlencoded 和 multipart/form-data 的请求报文body的参数 swagger指

  • 浅谈django框架集成swagger以及自定义参数问题

    介绍 我们在实际的开发工作中需要将django框架与swagger进行集成,用于生成API文档.网上也有一些关于django集成swagger的例子,但由于每个项目使用的依赖版本不一样,因此可能有些例子并不适合我们.我也是在实际集成过程中遇到了一些问题,例如如何自定义参数等问题,最终成功集成,并将结果分享给大家. 开发版本 我开发使用的依赖版本,我所使用的都是截止发稿日期为止最新的版本: Django 2.2.7 django-rest-swagger 2.2.0 djangorestframe

  • django-rest-framework 自定义swagger过程详解

    前言 之前的文章编写了一个返回json的例子,直接用浏览器进行get请求虽然成功了, 但是接口文档的样式很难看, 不好用. 而且提示没有访问权限. 我们一般都希望能够直接在接口文档中进行请求, 以测试接口, 本篇文章中会给出一个自定义swagger(openapi)的例子. 使接口文档变得美观可用, 可以填写参数, 可以进行请求以观察数据格式, 测试接口是否可用. 环境 workon python35 pip list chardet (3.0.4) coreapi (2.3.3) coresc

  • django-rest-swagger的优化使用方法

    如下所示: requirements.txt django==1.10.5 djangorestframework==3.5.3 django-rest-swagger==2.1.1 参考英文文档: http://django-rest-swagger.readthedocs.io/en/latest/ 使用swagger工具结合Django-rest-framework进行restful API的管理以及可视化显示的时候,由于swagger2.1以后不再使用yaml文档描述api,改而使用js

  • django-rest-swagger对API接口注释的方法

    Swagger是一个API开发者的工具框架,用于生成.描述.调用和可视化RESTful风格的Web服务.总体目标是使客户端和文件系统服务器以同样的速度来更新,方法,参数和模型紧密集成到服务器端的代码中,允许API始终保持同步. 在使用 django-rest-framework 进行API开发,可以使用django-rest-swagger接入swagger自动生成接口文档. 1. 安装django-rest-swagger pip install django-rest-swagger 2.配

  • Go语言使用swagger生成接口文档的方法

    swagger介绍 Swagger本质上是一种用于描述使用JSON表示的RESTful API的接口描述语言.Swagger与一组开源软件工具一起使用,以设计.构建.记录和使用RESTful Web服务.Swagger包括自动文档,代码生成和测试用例生成. 在前后端分离的项目开发过程中,如果后端同学能够提供一份清晰明了的接口文档,那么就能极大地提高大家的沟通效率和开发效率.可是编写接口文档历来都是令人头痛的,而且后续接口文档的维护也十分耗费精力. 最好是有一种方案能够既满足我们输出文档的需要又能

  • go swagger生成接口文档使用教程

    目录 前言 Swagger介绍 1.安装 2.检测是否安装成功 3.安装gin-swagger扩展 使用 1.添加注释 2.生成接口文档数据 3.引入gin-swagger渲染文档数据 总结 前言 这篇文章主要介绍了Go语言使用swagger生成接口文档的方法,希望能够对大家的学习或工作具有一定的帮助,需要的朋友可以参考下. 在前后端分离的项目开发过程中,如果后端同学能够提供一份清晰明了的接口文档,那么就能极大地提高大家的沟通效率和开发效率.那如何维护接口文档,历来都是令人头痛的,感觉很浪费精力

  • golang组件swagger生成接口文档实践示例

    目录 swagger介绍 gin-swagger实战 第一步:添加注释 第二步:生成接口文档数据 第三步:引入gin-swagger渲染文档数据 swagger介绍 Swagger本质上是一种用于描述使用JSON表示的RESTful API的接口描述语言.Swagger与一组开源软件工具一起使用,以设计.构建.记录和使用RESTful Web服务.Swagger包括自动文档,代码生成和测试用例生成. 在前后端分离的项目开发过程中,如果后端同学能够提供一份清晰明了的接口文档,那么就能极大地提高大家

  • SpringBoot集成Swagger2生成接口文档的方法示例

    我们提供Restful接口的时候,API文档是尤为的重要,它承载着对接口的定义,描述等.它还是和API消费方沟通的重要工具.在实际情况中由于接口和文档存放的位置不同,我们很难及时的去维护文档.个人在实际的工作中就遇到过很多接口更新了很久,但是文档却还是老版本的情况,其实在这个时候这份文档就已经失去了它存在的意义.而 Swagger 是目前我见过的最好的API文档生成工具,使用起来也很方便,还可以直接调试我们的API.我们今天就来看下 Swagger2 与 SpringBoot 的结合. 准备工作

  • 教你利用springboot集成swagger并生成接口文档

    效果图 实现步骤 1.maven中引入jar包,不同版本的swagger可能页面效果不一样. <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.1</version> </dependency> <dependency> <groupId&g

  • SpringBoot使用swagger生成api接口文档的方法详解

    目录 前言 具体例子 maven配置 项目application.yml配置 springApplication添加swagger注解 在控制层添加swagger注解 前言 在之前的文章中,使用mybatis-plus生成了对应的包,在此基础上,我们针对项目的api接口,添加swagger配置和注解,生成swagger接口文档 具体可以查看本站spring boot系列文章: spring boot项目使用mybatis-plus代码生成实例 具体例子 maven配置 在使用之前,我们需要添加s

  • java集成开发SpringBoot生成接口文档示例实现

    目录 为什么要用Swagger ? Swagger集成 第一步: 引入依赖包 第二步:修改配置文件 第三步,配置API接口 Unable to infer base url For input string: "" Swagger美化 第一步: 引入依赖包 第二步:启用knife4j增强 Swagger参数分组 分组使用说明 1.在bean对象的属性里配置如下注释 2.在接口参数的时候加入组规则校验 小结 大家好,我是飘渺. SpringBoot老鸟系列的文章已经写了两篇,每篇的阅读反

  • Spring boot集成swagger2生成接口文档的全过程

    一.Swagger介绍 Swagger是一个规范和完整的框架,用于生成.描述.调用和可视化RESTful风格的web服务.目标是使客户端和文件系统作为服务器以同样的速度来更新文件的方法,参数和模型紧密集成到服务器.这个解释简单点来讲就是说,swagger是一款可以根据restful风格生成的接口开发文档,并且支持做测试的一款中间软件. 二.使用swagger优势 1.对于后端开发人员来说 不用再手写Wiki接口拼大量参数,避免手写错误 对代码侵入性低,采用全注解的方式,开发简单 方法参数名修改.

  • SpringBoot整合Swagger3生成接口文档过程解析

    前后端分离的项目,接口文档的存在十分重要.与手动编写接口文档不同,swagger是一个自动生成接口文档的工具,在需求不断变更的环境下,手动编写文档的效率实在太低.与新版的swagger3相比swagger2配置更少,使用更加方便. 一.pom文件中引入Swagger3依赖 <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId

  • java快速生成接口文档的三种解决方案

    目录 前言 方案一,使用japidocs 基本用法 方案2,swagger + knife4j 生成步骤 方案3,开源的接口文档生成工具 总结 前言 常常在项目收尾阶段,客户需要项目的接口文档,或者是一个大的sass平台,各个产品之间互相调用的时候,需要对方提供接口文档 通常来说,接口文档属于产品的技术沉淀,是一个长期积累的过程,然而,很多时候,开发阶段并不会想的那么多,结果到了需要接口文档的时候总是疲于应付,情急之下,往往采用最笨拙的办法,就是对照着项目代码,一个个拷贝吧 下面针对这个情况,小

随机推荐