0 Comments
Hits

Swagger 简介 - Gin框架

Swagger 简介

Swagger是一个强大的API文档构建工具，可以自动为Restful API生成Swagger格式的文档，可以在浏览器中查看API文档，也可以通过调用接口返回API文档（JSON格式）。Swagger通常可以展示如下信息：

  • HTTP 方法（GET、POST、PUT、DELETE等）
  • URL 路径
  • HTTP 消息体（消息体中的参数名和类型）
  • 参数位置
  • 参数是否必选
  • 返回的参数（参数名和类型）
  • 请求和返回的媒体类型

Swagger还有一个强大的功能：可以通过API文档描述的请求参数来构建请求，测试API。

JSON 返回截图：

swagger配置步骤

主要用gin-swagger gin middleware 来生成swagger API文档。步骤如下：

  • 安装 swag 命令
$ mkdir -p $GOPATH/src/github.com/swaggo
$ cd $GOPATH/src/github.com/swaggo
$ git clone https://github.com/swaggo/swag
$ cd swag/cmd/swag/
$ go install -v

因为该包引用 golang.org 中的包，而网络环境原因，一般很难连上 golang.org，所以这里不采用 go get -u github.com/swaggo/swag 方式安装。

swag 的依赖包已经包含在第 4 节的 vendor 包下。

  • 进入 apiserver 根目录执行 swag init
$ cd $GOPATH/src/apiserver
$ swag init
  • 下载 gin-swagger
$ cd $GOPATH/src/github.com/swaggo
$ git clone https://github.com/swaggo/gin-swagger
  • 在 router/router.go 中添加 swagger 路由

https://img.lg1024.com/blog/img/swagger3.jpg

  • 编写 API 注释，Swagger 中需要将相应的注释或注解编写到方法上，再利用生成器自动生成说明文件
package user

import (
    ...
)

// @Summary Add new user to the database
// @Description Add a new user
// @Tags user
// @Accept  json
// @Produce  json
// @Param user body user.CreateRequest true "Create a new user"
// @Success 200 {object} user.CreateResponse "{"code":0,"message":"OK","data":{"username":"kong"}}"
// @Router /user [post]
func Create(c *gin.Context) {
    ...
}
  • 执行 swag init，在 apiserver 根目录下生成 docs 目录
$ swag init

文档语法说明

  • Summary：简单阐述 API 的功能
  • Description：API 详细描述
  • Tags：API 所属分类
  • Accept：API 接收参数的格式
  • Produce：输出的数据格式，这里是 JSON 格式
  • Param：参数，分为 6 个字段，其中第 6 个字段是可选的，各字段含义为：
    • 参数名称
    • 参数在 HTTP 请求中的位置（body、path、query）
    • 参数类型（string、int、bool 等）
    • 是否必须（true、false）
    • 参数描述
    • 选项，这里用的是 default() 用来指定默认值
  • Success：成功返回数据格式，分为 4 个字段
    • HTTP 返回 Code
    • 返回数据类型
    • 返回数据模型
    • 说明
  • 路由格式，分为 2 个字段：
    • API 路径
    • HTTP 方法

API 文档编写规则请参考 See Declarative Comments Format。 API 文档有更新时，要重新执行 swag init 并重新编译 apiserver。

本文链接：，参与评论 »

--EOF--

发表于 2018-06-26 17:26:00。

本站使用「署名 4.0 国际」创作共享协议，转载请注明作者及原网址。更多说明 »

提醒：本文最后更新于 356 天前，文中所描述的信息可能已发生改变，请谨慎使用。

Comments