首页 > 其他分享 >使用swagger生成接口文档

使用swagger生成接口文档

时间:2022-12-11 15:34:13浏览次数:67  
标签:github global 接口 文档 go gin swagger com

1、安装

go get -u github.com/swaggo/swag/cmd/swag
go get -u github.com/swaggo/gin-swagger 
go get -u github.com/swaggo/files
go get -u github.com/alecthomas/template

  

验证安装成功与否

$ swag -v
swag version v1.8.8

  

2、写注释

注解说明

注解描述
@Summary 摘要
@Produce API 可以产生的 MIME 类型的列表,MIME 类型你可以简单的理解为响应类型,例如:json、xml、html 等等
@Param 参数格式,从左到右分别为:参数名、入参类型、数据类型、是否必填、注释
@Success 响应成功,从左到右分别为:状态码、参数类型、数据类型、注释
@Failure 响应失败,从左到右分别为:状态码、参数类型、数据类型、注释
@Router 路由,从左到右分别为:路由地址,HTTP 方法

实例:

// @title 博客系统
// @version 1.0
// @description Go 语言编程之旅:一起用 Go 做项目
// @termsOfService https://github.com/go-programming-tour-book
func main() {
	global.Logger.Infof("%s: go-programming-tour-book/%s", "eddycjy", "blog-service")
	gin.SetMode(global.ServerSetting.RunMode)
	router := routers.NewRouter()
	s := &http.Server{
		Addr:           ":" + global.ServerSetting.HttpPort,
		Handler:        router,
		ReadTimeout:    global.ServerSetting.ReadTimeout,
		WriteTimeout:   global.ServerSetting.WriteTimeout,
		MaxHeaderBytes: 1 << 20,
	}
	s.ListenAndServe()
}



// @Summary 获取多个标签
// @Produce  json
// @Param name query string false "标签名称" maxlength(100)
// @Param state query int false "状态" Enums(0, 1) default(1)
// @Param page query int false "页码"
// @Param page_size query int false "每页数量"
// @Success 200 {object} model.Tag "成功"
// @Failure 400 {object} errcode.Error "请求错误"
// @Failure 500 {object} errcode.Error "内部错误"
// @Router /api/v1/tags [get]
func (t Tag) List(c *gin.Context) {}

// @Summary 新增标签
// @Produce  json
// @Param name body string true "标签名称" minlength(3) maxlength(100)
// @Param state body int false "状态" Enums(0, 1) default(1)
// @Param created_by body string true "创建者" minlength(3) maxlength(100)
// @Success 200 {object} model.Tag "成功"
// @Failure 400 {object} errcode.Error "请求错误"
// @Failure 500 {object} errcode.Error "内部错误"
// @Router /api/v1/tags [post]
func (t Tag) Create(c *gin.Context) {}

// @Summary 更新标签
// @Produce  json
// @Param id path int true "标签 ID"
// @Param name body string false "标签名称" minlength(3) maxlength(100)
// @Param state body int false "状态" Enums(0, 1) default(1)
// @Param modified_by body string true "修改者" minlength(3) maxlength(100)
// @Success 200 {array} model.Tag "成功"
// @Failure 400 {object} errcode.Error "请求错误"
// @Failure 500 {object} errcode.Error "内部错误"
// @Router /api/v1/tags/{id} [put]
func (t Tag) Update(c *gin.Context) {}

// @Summary 删除标签
// @Produce  json
// @Param id path int true "标签 ID"
// @Success 200 {string} string "成功"
// @Failure 400 {object} errcode.Error "请求错误"
// @Failure 500 {object} errcode.Error "内部错误"
// @Router /api/v1/tags/{id} [delete]
func (t Tag) Delete(c *gin.Context) {}

  

3、生成

swag init

在执行命令完毕后,会发现在 docs 文件夹生成 docs.goswagger.jsonswagger.yaml 三个文件。

 

4、路由

import (
        ...

	_ "gin_blog/docs"   //这里引入自己的docs
	swaggerFiles "github.com/swaggo/files"
	ginSwagger "github.com/swaggo/gin-swagger"
)

func NewRouter() *gin.Engine {
	r := gin.New()
	r.Use(gin.Logger())
	r.Use(gin.Recovery())
	r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

	...
	return r
}

  

5、访问接口文档

在浏览器中访问 Swagger 的地址 http://127.0.0.1:8000/swagger/index.html,就可以看到文档,其主要分为三个部分,分别是项目主体信息、接口路由信息、模型信息,这三部分共同组成了我们主体内容。

 

 

参考:

生成接口文档 | Go 语言编程之旅 (eddycjy.com)

(37条消息) 基于golang的swagger超贴心、超详细使用指南【有很多坑】_【阿冰】的博客-CSDN博客

 

标签:github,global,接口,文档,go,gin,swagger,com
From: https://www.cnblogs.com/mango1997/p/16973735.html

相关文章

  • 【ASP.NET Core】MVC控制器的各种自定义:IActionHttpMethodProvider 接口
    IActionHttpMethodProvider接口的结构很简单,实现该接口只要实现一个属性即可——HttpMethods。该属性是一个字符串序列。这啥意思呢?这个字符串序列代表的就是受支持的HT......
  • 网络安全中接口测试的解决方案
    Eolink新一代API测试神器​​一、接口测试​​​​1、接口​​​​2、接口测试​​​​二、网络安全中的接口测试,具体场景​​​​1、接口安全测试​​​​2、传统测试工具......
  • Eolink神技之一、基于数据库智能生成API文档
    Eolink神技之一、基于数据库智能生成API文档目录​​Eolink神技之一、基于数据库智能生成API文档​​​​Eolink数据库智能API文档解决的问题​​​​演示流程​​​​一、......
  • Collection接口中声明的方法
    Collection方法1~13@Test  publicvoidtest1(){    Collectioncoll=newArrayList();    coll.add(123);    coll.add(456);   ......
  • 接口测试
    一、接口测试灵魂拷问1.什么是接口接口就是软件提供给外部的服务,用于做数据传输接口包括内部接口和外部接口:内部接口:开发人员自己开发的对自身系统提供的接口外......
  • books一系列接口
    drf数据的增删改查目录drf数据的增删改查模型类序列化类路由配置视图类模型类fromdjango.dbimportmodelsclassBaseModel(models.Model):is_delete=models......
  • 异常处理,统一接口
    异常处理,统一接口#全局配置REST_FRAMEWORK={'EXCEPTION_HANDLER':'app01.app_auth.exception_handler',}#统一接口的返回#app_auth.py#自定义异常处理的方......
  • winform 实现文档预览。
      文档预览一直是一个问题,尤其是web网站,实现文档预览,淡然如果你付费第三方,当我没说。微软给的接口实现预览效果还可以,但是他又限制,就是ip不行,需要域名。这个就有点苦逼......
  • spring——Spring自动装配(基于注解)——前提了解——Spring的@Autowired注解为什么用在
    大家都知道@Service注入的是实现类serviceImpl,那使用时怎么能获取到接口,而且还能调用到实现类的方法。 接口:publicinterfaceTestService{publicStri......
  • API接口文档实例
    接口描述获取接口统一鉴权码token接口,此接口调用需要appid凭证和secret密钥,每个微信只有一对请求URLhttps://api.weixin.qq.com/cgi-bin/token?grant_type=client_cr......