gin框架之用swagger自动生成API文档

大话swift

发布于 2020-03-13 02:13:04

2.2K0

发布于 2020-03-13 02:13:04

这篇文章我们讲解swagger的使用

我们在工作当中经常需要用到接口文档，那么怎么写接口文档呢？又会遇到哪些坑呢？刚开始的时候，我们用word写文档，后来我们用markdown写文档。但是这些方式不利于维护，到后来我们发现，接口改了，文档还是原来的样子，不利于维护。而且每次我们都需要用postman工具进行接口开发测试，及其繁琐麻烦。我在无意当中发现了swagger，从此喜爱上用swagger写文档。他不接可以自动生成文档，而且可以直接用来做接口测试。

首先安装 swagger

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

go get -u github.com/swaggo/gin-swagger/swaggerFiles

1、入口文件引入swagger配置

package main

import (  "ginLearn.com/controller"  _ "ginLearn.com/docs"  "github.com/gin-gonic/gin"  "github.com/swaggo/gin-swagger"  "github.com/swaggo/gin-swagger/swaggerFiles")

// @title Gin swagger// @version 1.0// @description Gin swagger 示例项目

// @contact.name hanyun// @contact.url// @contact.email 1355081829@qq.com

// @license.name Apache 2.0// @license.url http://www.apache.org/licenses/LICENSE-2.0.html// @host localhost:8080func main() {  router := gin.Default()  router.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))  router.GET("/api/v1", controller.Index)  router.Run()}

值得注意的一点是，已定义记着定义`_ "ginLearn.com/docs"`,要不swagger无法正常的解析页面，因为我是采用gomodule的方式，我定义的`module ginLearn.com`，各位可以把“ginLearn.com”替换为自己定义的。

swagger服务注释解释说明

// @title Gin swagger  展示在web端的title上// @version 1.0 定义接口的版本// @description Gin swagger 示例项目 首页展示// @securityDefinitions.apikey ApiKeyAuth  API的认证方式// @in header 发送认证的方式// @name Authorization  后端获取认证值得方式

// @contact.name hanyun 联系人信命// @contact.url 联系人的个人首页地址// @contact.email 1355081829@qq.com 联系人的邮箱

// @license.name Apache 2.0 文档采用的协议// @license.url http://www.apache.org/licenses/LICENSE-2.0.html 协议地址// @host localhost:8080 文档服务器的地址

2、在具体的方法上添加注释

package controller

import (  "ginLearn.com/response"  "github.com/gin-gonic/gin")

// @Tags 首页// @Id 1// @Summary 获得首页数据// @Description | 项目 | 价格 | 数量 |// @Description | :-------- | --------:| :--: |// @Description | iPhone | 6000 元 | 5 |// @Description | iPad | 3800 元 | 12 |// @Description | iMac | 10000 元 | 234 |// @Produce  json// @Security ApiKeyAuth// @Param id path int true "用户id"// @Param token header string true "用户token"// @Param name query string false "用户名"// @Param img formData file false "文件"// @Success 200 object  response.Result "成功"// @Failure 400 object  response.Result "失败"// @Router /api/v1/{id} [get]func Index(c *gin.Context) {  c.JSON(4000, response.Result{})}

swagger接口注释解释说明

@Summary 是对该接口的一个描述@Id 是一个全局标识符，所有的接口文档中 Id 不能标注@Tags 是对接口的标注，同一个 tag 为一组，这样方便我们整理接口@Security ApiKeyAuth 表示这是一个需要认证才可以调用的接口，对应// @securityDefinitions.apikey ApiKeyAuth@Version 表明该接口的版本@Accept 表示该该请求的请求类型@Param 表示参数 分别有以下参数 参数名词 参数类型 数据类型 是否必须 注释 属性(可选参数),参数之间用空格隔开。@Success 表示请求成功后返回，它有以下参数 请求返回状态码，参数类型，数据类型，注释@Failure 请求失败后返回，参数同上@Router 该函数定义了请求路由并且包含路由的请求方式。

有时候我们写文档需要markdown表格,swagger的注释也支持markdown语法

// @Description | 项目 | 价格 | 数量 |// @Description | :-------- | --------:| :--: |// @Description | iPhone | 6000 元 | 5 |// @Description | iPad | 3800 元 | 12 |// @Description | iMac | 10000 元 | 234 |

本文参与腾讯云自媒体分享计划，分享自微信公众号。

原始发表：2020-03-12，如有侵权请联系 cloudcommunity@tencent.com 删除

java