使用 OpenAPI 构建 API 文档

作为一名开发者，往往需要编写程序的 API 文档，尤其是 Web 后端开发者，在跟前端对接 HTTP 接口的时候，一个好的 API 文档能够大大进步协作功率，下降交流本钱，本文就来聊聊如何运用 OpenAPI 构建 HTTP 接口文档。

OpenAPI

什么是 OpenAPI

OpenAPI 是标准化描绘 API 范畴运用最广泛的行业标准，由 OpenAPI Initiative(OAI) 界说并保护，同时也是 Linux 基金会下的一个开源项目。通常咱们所说的 OpenAPI 全称应该是 OpenAPI Specification(OpenAPI 标准，简称 OSA)，它运用规则的格局来描绘 HTTP RESTful API 的界说，以此来标准 RESTful 服务开发过程。运用 JSON 或 YAML 来描绘一个标准的、与编程言语无关的 HTTP API 接口。OpenAPI 标准开始依据 SmartBear Software 在 2015 年捐赠的 Swagger 标准演变而来，现在最新的版别是 v3.1.0。

简略来说，OpenAPI 便是用来界说 HTTP 接口文档的一种标准，咱们都按照同一套标准来编写接口文档，能够极大的减少交流本钱。

OpenAPI 标准基本信息

OpenAPI 标准内容包括十分多的细节，本文无法一一解说，这儿仅介绍常见的基本信息，以 YAML 为例进行阐明。YAML 是 JSON 的超集，在 OpenAPI 标准中界说的一切语法，两者之间是能够相互转换的，假如手动编写，建议编写 YAML 格局，更为易读。

OpenAPI 文档编写在一个 .json 或 .yaml 中，引荐将其命名为 openapi.json 或 openapi.yaml，OpenAPI 文档其实便是一个单一的 JSON 目标，其间包括契合 OpenAPI 标准中界说的结构字段。

OpenAPI 标准基本信息如下：

字段名	类型	描绘
openapi	string	必选，有必要是 OpenAPI 已发布的合法版别，如 3.0.1。
info	object	必选，此字段供给 API 相关的元数据（如描绘、作者和联络信息）。
servers	array[object]	这是一个 Server 目标的数组，供给到服务器的连接信息。
paths	object	必选，API 供给的可用的途径和操作。
components	object	一个包括多种结构的元素，可复用组件。
security	array	声明 API 运用的安全认证机制，现在支撑 HTTP Basic Auth、HTTP Bearer Auth、ApiKey Auth 以及 OAuth2。
tags	array	供给标签能够为 API 归类，每个标签名都应该是仅有的。
externalDocs	object	附加的文档，能够经过扩展特点来扩展文档。

一个 YAML 格局的 OpenAPI 文档示例如下：

openapi: 3.1.0
info:
  title: Tic Tac Toe
  description: |
    This API allows writing down marks on a Tic Tac Toe board
    and requesting the state of the board or of individual squares.
  version: 1.0.0 # 此为 API 接口文档版别，与 openapi 版别无关
tags:
  - name: Gameplay
paths:
  # Whole board operations
  /board:
    get:
      summary: Get the whole board
      description: Retrieves the current state of the board and the winner.
      tags:
        - Gameplay
      operationId: get-board
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/status"
  # Single square operations
  /board/{row}/{column}:
    parameters:
      - $ref: "#/components/parameters/rowParam"
      - $ref: "#/components/parameters/columnParam"
    get:
      summary: Get a single board square
      description: Retrieves the requested square.
      tags:
        - Gameplay
      operationId: get-square
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/mark"
        "400":
          description: The provided parameters are incorrect
          content:
            text/html:
              schema:
                $ref: "#/components/schemas/errorMessage"
              example: "Illegal coordinates"
...

以上示例完好文档在此，详细语法我就不在这儿介绍了。假如你开发过 API 接口，信任能看懂文档大部分内容所代表的意义。不必完全掌握其语法，这并不会对阅览本文接下来的内容造成困扰，由于稍后我会介绍如何经过代码注释的方式主动生成此文档。

假如你想手动编写 OpenAPI 文档，那么我仍是引荐你阅览下 OpenAPI 标准，这儿有一份中文版的标准。阅览标准是一个比较单调的过程，假如你没有耐心读完，强烈建议阅览 OpenAPI 标准入门，相较于完好版的标准要精简得多，而且解说愈加易于了解。

别的还引荐拜访 OpenAPI Map 网站来掌握 OpenAPI 标准，该网站以思想导图的形式展现标准的格局以及阐明。

OpenAPI.Tools

现在咱们知道了 OpenAPI 标准，接下来要做什么？当然是了解 OpenAPI 开放了哪些才能。

有一个叫 OpenAPI.Tools 的网站，分类整理并记录了社区环绕 OpenAPI 标准开发的盛行东西。

能够看到列表中有很多分类，在咱们日常开发中，最常常运用的有三类：

文档编辑器

文档编辑器便利咱们用来编写契合 OpenAPI 标准的文档，有助于进步编写文档的功率，就像 VS Code 能够便利咱们编写代码一样。

文档编辑器有两种：文本编辑器 以及 图形编辑器。

文本编辑器引荐运用在线的 Swagger Editor，能够完成格局校验和实时预览 Swagger 交互式 API 文档功用，作用如下图所示：

假如你习惯运用 VS Code，也有相应插件可供运用。

图形编辑器的优点是能够以可视化的形式编辑内容，不了解 OpenAPI 标准语法也能编辑。能够依据自己喜好来进行选择，如 Stoplight Studio、APIGit 等。

Mock 服务器

当咱们运用 OpenAPI 标准来进行接口开发时，往往采用文档先行的策略，也便是前后端在开发代码前，先界说好接口文档，再进行代码的编写。此时前端假如想测验接口可用性，而后端代码还没有编写完成，Mock 服务器就派上用场了。Mock 服务器能够依据所供给的 OpenAPI 接口文档，主动生成一个模仿的 Web Server。运用 Mock 服务器能够轻松模仿真实的后端接口，便利前端同学进行接口调试。

上面说到的 APIGit 也同时具备此功用。

代码生成器

还有一种很有用的东西是代码生成器，代码生成器有两种类型：一种是从代码/注释生成 OpenAPI 文档，另一种是从 OpenAPI 文档生成代码。

这类东西相同十分多，且更为有用。比方咱们有一份写好了的 Go Web Server 代码，想要主动生成一份 OpenAPI 文档，就能够运用 go-swagger 这个东西来生成一份 openapi.yaml 文档。

而假如咱们有一份 openapi.yaml 文档，就能够利用 go-swagger 生成一份 Go SDK 代码，乃至它还能依据这份 OpenAPI 文档生成 Go Web Server 的结构代码，咱们只需要在对应的接口里面完成详细的事务逻辑即可。

不只 Go 言语有这样的东西，像 Swagger Codegen 和 OpenAPI Generator 这类东西更是支撑几乎一切主流编程言语。

代码生成器是开发者应该侧重重视的东西，运用这些东西能够减少很多手动且重复的工作，你能够在此看下有没有感兴趣的项目供你运用。

Swagger

什么是 Swagger

Swagger 是一套环绕 OpenAPI 标准所构建的开源东西集，供给了强壮和易于运用的东西来充分利用 OpenAPI 标准，Swagger 东西集由开始的 Swagger 标准背面的团队所开发。

Swagger 东西集供给了 API 规划、开发、测验、管理和监控等才能，其间最主要的东西包括如下三个：

• Swagger Codegen：依据 OpenAPI 标准界说生成服务器存根和客户端 SDK。

• Swagger Editor：依据浏览器的在线 OpenAPI 标准编辑器。

• Swagger UI：以 UI 界面的方式可视化展示 OpenAPI 标准界说，而且能够在浏览器中进行交互。

当然 Swagger 也有为企业用户供给的收费版别东西，如 SwaggerHub Enterprise，感兴趣的同学能够自行了解。

Swagger 和 OpenAPI 的关系

讲到了 Swagger，就不得不提及 Swagger 和 OpenAPI 的联络与区别，由于这二者常常在一起呈现。

前文也说过 OpenAPI 标准是依据 Swagger 标准演变而来的，但其实二者并不相等。

在 OpenAPI 尚未呈现之前，Swagger 代表了 Swagger 标准以及一系列环绕 Swagger 标准的开源东西集。Swagger 标准最终一个版别是 2.0，之后就捐赠给了 OAI 并被重新命名为 OpenAPI 标准，所以 OpenAPI 标准第一个版别是 2.0，也便是 Swagger 标准 2.0，而由 OAI 这个组织发布的第一个 OpenAPI 标准正式版别是 3.0.0。

现在，Swagger 标准已被 OpenAPI 标准完全接管并替代。OpenAPI 代表了 OpenAPI 标准以及一系列生态，而 Swagger 则是这个生态中的一部分，是 Swagger 团队环绕 OpenAPI 标准所开发的一系列东西集。

Swagger 是 OpenAPI 生态中十分重要的组成部分，由于它给出了一整套方案，且十分盛行。

Swagger 和 OpenAPI 二者 LOGO 对比方下：

期望你下次再见到这两个 LOGO 时能清晰分辨出二者，而不被混淆。

以 Go 言语为例解说 OpenAPI 在实践开发中的运用

前文介绍了编写 OpenAPI 文档的两种编辑器：文本编辑器以及图形编辑器。在日常开发中，后端能够先运用这类编辑器如 Swagger Editor 编写出 OpenAPI 文档，然后将这份文档交给前端，前端拿到 OpenAPI 文档后将其导入到 Swagger Editor，就能够在线阅览接口文档并与之进行交互，之后前后端就能够并行开发了。

这样的工作流看起来似乎没什么问题，不过编写 OpenAPI 文档毕竟是个苦力活，不只要很多的重复工作，还要求开发者熟练掌握 OpenAPI 标准语法。这关于“爱偷懒”的开发者明显是无法接受的，就像段子里说的，程序员最厌烦两件事：1. 写文档，2. 他人不写文档。而这个问题的解法，当然便是前文说到的代码生成器。

运用 Swag 生成 Swagger 文档

在 Go 言语生态里，现在有两个比较盛行的开源东西能够生成 Swagger 文档，别离是 go-swagger 和 swag。它们都能依据代码中的注释生成 Swagger 文档，go-swagger 作为一款 OpenAPI.Tools 引荐的东西，其功用比 swag 愈加强壮且 Github Star 数量也更高。

不过本文将选择 swag 来进行介绍，一是由于 swag 比较轻量，更适合微服务开发；二是假如运用 swag，那么注释代码会离接口代码更近，晋级时便利保护。假如你有更高档的需求，如依据 Swagger 文档生成客户端 SDK，服务端存根等，则引荐运用 go-swagger。

留意：在这儿我一向说到的都是生成 Swagger 文档，而没有说是 OpenAPI 文档。由于无论是 swag 仍是功用更强壮的 go-swagger，它们现在都仅支撑生成 OpenAPI 2.0 文档，并不支撑生成 OpenAPI 3.0+ 文档，而 OpenAPI 2.0 版别咱们更习惯称其为 Swagger 文档。

装置 Swag

运用 go install 指令即可装置。

$ go install github.com/swaggo/swag/cmd/swag@latest # 装置
$ swag --version # 检查版别
swag version v1.8.10

Swag 指令行东西

swag 十分简练，仅供给了两个主要指令 init 和 fmt：

$ swag -h # 检查协助
NAME:
   swag - Automatically generate RESTful API documentation with Swagger 2.0 for Go.
USAGE:
   swag [global options] command [command options] [arguments...]
VERSION:
   v1.8.10
COMMANDS:
   init, i  Create docs.go
   fmt, f   format swag comments
   help, h  Shows a list of commands or help for one command
GLOBAL OPTIONS:
   --help, -h     show help (default: false)
   --version, -v  print the version (default: false)

• 在包括 main.go 文件（默许情况下）的项目根目录运行 swag init 指令，将会解析 swag 注释并生成 docs/ 目录以及 /docs/docs.go、docs/swagger.json、docs/swagger.yaml 三个文件。

$ swag init -h # 检查 init 子指令运用方法
NAME:
   swag init - Create docs.go
USAGE:
   swag init [command options] [arguments...]
OPTIONS:
   --quiet, -q                            不在控制台输出日志 (default: false)
   --generalInfo value, -g value          API 通用信息地点的 Go 源文件途径，假如是相对途径则依据 API 解析目录 (default: "main.go")
   --dir value, -d value                  API 解析目录，多个目录可用逗号分隔 (default: "./")
   --exclude value                        解析扫描时扫除的目录，多个目录可用逗号分隔
   --propertyStrategy value, -p value     结构体字段命名规则，三种：snake_case，camelCase，PascalCase (default: "camelCase")
   --output value, -o value               一切生成文件的输出目录（swagger.json, swagger.yaml and docs.go）(default:"./docs")
   --outputTypes value, --ot value        生成文件的输出类型（docs.go, swagger.json, swagger.yaml）三种：go,json,yaml (default: "go,json,yaml")
   --parseDependency, --pd                解析依靠目录中的 Go 文件 (default: false)
   --markdownFiles value, --md value      指定 API 的描绘信息所运用的 Markdown 文件地点的目录，默许禁用
   --parseInternal                        解析 internal 包中的 Go 文件 (default: false)
   --generatedTime                        输出时间戳到输出文件 `docs.go` 顶部 (default: false)
   --parseDepth value                     依靠项解析深度 (default: 100)
   --requiredByDefault                    默许情况下，为一切字段设置 `required` 验证 (default: false)
   --instanceName value                   设置文档实例名 (default: "swagger")
   --parseGoList                          经过 'go list' 解析依靠关系 (default: true)
   --tags value, -t value                 逗号分隔的标签列表，用于过滤指定标签生成 API 文档。特殊情况下，假如标签前缀是 '!' 字符，那么带有该符号的 API 将被扫除
   --help, -h                             显现协助信息 (default: false)

留意：以上 swag init 指令可选参数介绍略有删减，只列出了常用选项，更完好的文档请参阅官方仓库。

• swag fmt 指令能够格局化 swag 注释。

$ swag fmt -h # 检查 fmt 子指令运用方法
NAME:
   swag fmt - format swag comments
USAGE:
   swag fmt [command options] [arguments...]
OPTIONS:
   --dir value, -d value          API 解析目录，多个目录可用逗号分隔 (default: "./")
   --exclude value                解析扫描时扫除的目录，多个目录可用逗号分隔
   --generalInfo value, -g value  API 通用信息地点的 Go 源文件途径，假如是相对途径则依据 API 解析目录 (default: "main.go")
   --help, -h                     显现协助信息 (default: false)

在 Gin 中运用 Swag

在 gin 结构能够很便利的运用 swag，过程如下：

1. 准备项目目录结构如下：

.
├── go.mod
├── go.sum
└── main.go

2. 初始化项目

$ go mod init gin-swag

3. 编写 main.go 代码如下：

package main
import (
	"net/http"
	"github.com/gin-gonic/gin"
)
// @title           Swagger Example API
// @version         1.0
// @schemes         http
// @host            localhost:8080
// @BasePath        /api/v1
// @tag.name        example
// @tag.description 示例接口
// Helloworld godoc
//
// @Summary     该操作的简略摘要
// @Description 操作行为的详细阐明
// @Tags        example
// @Accept      json
// @Produce     json
// @Success     200 {string} string "Hello World!"
// @Router      /example/helloworld [get]
func Helloworld(g *gin.Context) {
	g.JSON(http.StatusOK, "Hello World!")
}
func main() {
	r := gin.Default()
	v1 := r.Group("/api/v1")
	{
		eg := v1.Group("/example")
		{
			eg.GET("/helloworld", Helloworld)
		}
	}
	if err := r.Run(":8080"); err != nil {
		panic(err)
	}
}

代码中的注释部分即为 swag 的注释语法，稍后经过这些注释生成 Swagger 文档。

其间通用 API 信息部分注释意义如下：

注释	阐明
@title	必填，运用程序的称号。
@version	必填，供给运用程序 API 的版别。
@schemes	用空格分隔的恳求传输协议。
@host	运行 API 的主机（主机名或 IP 地址）。
@BasePath	运行 API 的基本途径。
@tag.name	标签的称号。
@tag.description	标签的描绘。

还有一部分注释代表了 API 操作，其意义如下：

注释	阐明
@Summary	该操作的简略摘要。
@Description	操作行为的详细阐明。
@Tags	该 API 操作的标签列表，多个标签以逗号分隔。
@Accept	API 能够接收的参数 MIME 类型列表。
@Produce	API 能够生成的参数 MIME 类型列表。
@Success	成功呼应。
@Router	路由途径界说。

以上这些注释最终都会对应到 OpenAPI 2.0 标准的某个字段上。更多阐明请参阅官方文档，而且官方也供给了中文文档。

4. 运用 swag 依据注释生成 Swagger 文档，在项目根目录下（.）履行 swag init，将得到新的目录结构：

.
├── docs
│ ├── docs.go
│ ├── swagger.json
│ └── swagger.yaml
├── go.mod
├── go.sum
└── main.go

能够发现 swag init 生成的三个文件 docs.go、swagger.json、swagger.yaml 默许都在 docs/ 目录下。

其间 swagger.json、swagger.yaml 正是契合 OpenAPI 2.0 标准的 JSON 和 YAML 接口文档，例如 swagger.yaml 内容如下：

basePath: /api/v1
host: localhost:8080
info:
  contact: {}
  title: Swagger Example API
  version: "1.0"
paths:
  /example/helloworld:
    get:
      consumes:
      - application/json
      description: 操作行为的详细阐明
      produces:
      - application/json
      responses:
        "200":
          description: Hello World!
          schema:
            type: string
      summary: 该操作的简略摘要
      tags:
      - example
schemes:
- http
swagger: "2.0"
tags:
- description: 示例接口
  name: example

对比上面代码中的注释，很容易将其对应起来，比较于直接编写 YAML 格局文档，明显在代码中编写注释更为简略。

将其仿制到 Swagger Editor 编辑器中即可检查 Swagger UI 预览。

将 Gin 作为 Swagger UI 服务器

上面咱们经过 swag 生成了 Swagger 文档，并手动将生成的 swagger.yaml 仿制到 Swagger Editor 编辑器进行 Swagger UI 预览。不过这么做明显有点费事，好在 swag 作者也考虑到了这一点，所以他又供给了别的两个项目 gin-swagger 和 files，能够直接将 gin 作为 Swagger UI 服务器，这样就不用每次都将 swagger.yaml 手动仿制到 Swagger Editor 编辑器才能完成 Swagger UI 预览。

运用过程如下：

1. 下载 gin-swagger、files

$ go get -u github.com/swaggo/gin-swagger
$ go get -u github.com/swaggo/files

2. 在代码中导入 gin-swagger、files

import "github.com/swaggo/gin-swagger" // gin-swagger middleware
import "github.com/swaggo/files" // swagger embed files

3. 注册 Swagger 文档路由地址

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

完好代码如下：

package main
import (
	"net/http"
	"github.com/gin-gonic/gin"
	swaggerFiles "github.com/swaggo/files"
	ginSwagger "github.com/swaggo/gin-swagger"
	"gin-swag/docs" // 当时包名为 gin-swag
)
// @title           Swagger Example API
// @version         1.0
// @schemes         http
// @host            localhost:8080
// @BasePath        /api/v1
// @tag.name        example
// @tag.description 示例接口
// Helloworld godoc
//
// @Summary     该操作的简略摘要
// @Description 操作行为的详细阐明
// @Tags        example
// @Accept      json
// @Produce     json
// @Success     200 {string} string "Hello World!"
// @Router      /example/helloworld [get]
func Helloworld(g *gin.Context) {
	g.JSON(http.StatusOK, "Hello World!")
}
func main() {
	// 会覆盖上面注释部分 title 特点的设置
	docs.SwaggerInfo.Title = "Swag Example API"
	r := gin.Default()
	v1 := r.Group("/api/v1")
	{
		eg := v1.Group("/example")
		{
			eg.GET("/helloworld", Helloworld)
		}
	}
	// Swagger 文档接口地址
	r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
	if err := r.Run(":8080"); err != nil {
		panic(err)
	}
}

4. 履行 go run main.go 发动服务，拜访 http://localhost:8080/swagger/index.html 即可检查 Swagger UI 交互式文档界面。

这个本地的 Swagger UI 服务器相同支撑交互式操作。

打开 /example/helloworld 这个接口，点击 Try it out。

接着，点击 Execute。

Swagger UI 将会依据文档的 Base URL 去恳求真正的接口（同时还会给出 cURL 发送恳求的指令，便利仿制运用），并将呼应成果展示出来。

同时后端服务器能够打印出恳求记录：

与前端对接时，咱们只需要将接口文档地址给到前端，前端就能够依据这个 Swagger UI 界面进行接口查阅和调试了，十分便利。

让 Swag 支撑多版别 API 文档

实践工作中，咱们的项目会比这个只要一个接口的 demo 复杂得多，同时 API 也可能会支撑多版别，比方 /api/v1、/api/v2，针对这些场景，我完成了一个运用示例 swag-example，供你参阅。

为了愈加便利的运用 swag 指令，在 swag-example 项目中，我把 swag fmt 和 swag init 指令都写在 Makefile 文件中，最重要的便是以下两条指令：

swag init -g internal/api/controller/v1/docs.go --exclude internal/api/controller/v2 --instanceName v1
swag init -g internal/api/controller/v2/docs.go --exclude internal/api/controller/v1 --instanceName v2

这两条指令别离生成 v1、v2 两个版别的 API 文档，这样能够将不同版别的接口分开展示，愈加清晰。

其间 -g 参数指明 API 通用注释信息地点的 Go 源文件途径，大型项目中为了坚持代码架构整洁，这些注释应该独立于一个文件，而不是直接写在 main.go 中。

--exclude 参数指明生成 Swagger 文档时，需要扫除的目录。能够发现，在生成 v1 版别接口文档时，我扫除了 v2 接口目录，在生成 v2 版别接口文档时，扫除了 v1 接口目录，这样就完成了多版别接口别离。

关于这个项目的更多细节就留给你自己去探索了，信任你阅览完代码后会有所收成。

Swag 运用建议

在前文介绍的 swag 运用流程中，不知道你有没有留意到，咱们是先编写的代码，然后再生成的 Swagger 文档，最终将这份文档交给前端运用。

这明显违反了「文档先行」的思想，实践工作中，咱们更多的时候是先跟前端约定好接口，然后后端供给 Swagger 文档供前端运用，最终才是前后端编码阶段。

要想解决这个问题，最直接的解决方案是不运用 swag 东西，而是直接运用 Swagger Editor 这种编辑器手写 Swagger 文档，这样就能完成文档先行了。

但这又违反了 OpenAPI 给出的「最佳实践」，引荐主动生成 Swagger 文档，而非手动编写。

我自己的解决方案是，依旧选择运用 swag 东西，不过在编写代码时，先写接口的结构代码，而不写详细的事务逻辑，这样就能够先经过接口注释生成 Swagger 文档，供前端运用，然后再编写事务代码。

别的，较为遗憾的是，现在 swag 生成的文档是 OpenAPI 2.0 版别，并不能直接生成 OpenAPI 3.0 版别，假如你想运用 OpenAPI 3.0 版别的文档，一个变通的方法是运用东西将 OpenAPI 2.0 文档转换成 OpenAPI 3.0，如前文说到的 Swagger Editor 就支撑此操作。

运用 ReDoc 风格的 API 文档

也许相较于 Swagger UI 多年不变的界面风格，你更喜欢 ReDoc 风格的 UI，那么 go-redoc 是一个比较不错的选择。

在 gin 中运用 go-redoc 十分简略，只需要将如下套路代码加入到咱们的 main.go 文件中即可。

import (
	"github.com/gin-gonic/gin"
	"github.com/mvrilo/go-redoc"
	ginRedoc "github.com/mvrilo/go-redoc/gin"
)
...
doc := redoc.Redoc{
    Title:       "Example API",
    Description: "Example API Description",
    SpecFile:    "./openapi.json", // "./openapi.yaml"
    SpecPath:    "/openapi.json",  // "/openapi.yaml"
    DocsPath:    "/docs",
}
r := gin.New()
r.Use(ginRedoc.New(doc))

现在完好代码如下：

package main
import (
	"net/http"
	"path"
	"runtime"
	"github.com/gin-gonic/gin"
	"github.com/mvrilo/go-redoc"
	ginRedoc "github.com/mvrilo/go-redoc/gin"
	swaggerFiles "github.com/swaggo/files"
	ginSwagger "github.com/swaggo/gin-swagger"
	"gin-swag/docs" // 当时包名为 gin-swag
)
// @title           Swagger Example API
// @version         1.0
// @schemes         http
// @host            localhost:8080
// @BasePath        /api/v1
// @tag.name        example
// @tag.description 示例接口
// Helloworld godoc
//
// @Summary     该操作的简略摘要
// @Description 操作行为的详细阐明
// @Tags        example
// @Accept      json
// @Produce     json
// @Success     200 {string} string "Hello World!"
// @Router      /example/helloworld [get]
func Helloworld(g *gin.Context) {
	g.JSON(http.StatusOK, "Hello World!")
}
func main() {
	// 会覆盖上面注释部分 title 特点的设置
	docs.SwaggerInfo.Title = "Swag Example API"
	_, filename, _, _ := runtime.Caller(0)
	doc := redoc.Redoc{
		Title:       "ReDoc Example API",
		Description: "ReDoc Example API Description",
		SpecFile:    path.Join(path.Dir(filename), "docs/swagger.json"),
		SpecPath:    "/swagger.json",
		DocsPath:    "/redoc",
	}
	r := gin.Default()
	v1 := r.Group("/api/v1")
	{
		eg := v1.Group("/example")
		{
			eg.GET("/helloworld", Helloworld)
		}
	}
	// Swagger 文档接口地址
	r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
	// 注册 Redoc 文档接口地址
	r.Use(ginRedoc.New(doc))
	if err := r.Run(":8080"); err != nil {
		panic(err)
	}
}

履行 go run main.go 发动服务，拜访 http://localhost:8080/redoc 即可检查 Redoc UI。

不过，相较于 Swagger UI，Redoc UI 有个坏处是不能完成交互式操作，假如仅以此作为文档查阅东西，没有交互式操作的需求，那么仍是比较引荐运用的。

更先进的 API 东西

除了 OpenAPI.Tools 引荐的开源东西，社区中其实还有很多其他优秀东西值得测验运用，比方我这儿要引荐的一款国产东西 Apifox，官方将其界说为 Apifox = Postman + Swagger + Mock + JMeter，集 API 规划/开发/测验 于一身。

Apifox 可谓一站式图形化东西，其功用十分强壮，就像前文说到的 APIGit 同时具备了编辑器和 Mock 服务器的功用，Apifox 有过之而无不及。

图形化东西上手难度不大，加上 Apifox 自身由国内开发，十分容易上手，所以本文也就不深入介绍了，你能够观看官方教程 21 分钟学会 Apifox 来学习运用。

期望此文能对你有所协助。

联络我

• 微信：jianghushinian
• 邮箱：jianghushinian007@outlook.com
• 博客地址：jianghushinian.cn/

参阅

OpenAPI 官网：www.openapis.org/

OpenAPI 入门：oai.github.io/Documentati…

OpenAPI 标准：spec.openapis.org/oas/latest.…

OpenAPI 标准中文版：openapi.apifox.cn/

OpenAPI 标准思想导图版：openapi-map.apihandyman.io/

OpenAPI.Tools：openapi.tools/

Swagger 官网：swagger.io/

swag：github.com/swaggo/swag

swag-example：github.com/jianghushin…

go-redoc：github.com/mvrilo/go-r…

Apifox 官网：www.apifox.com/