🔥 开源地址open in new window

第10节如何生成 Swagger API 文档

❤️💕💕During the winter vacation, I followed up and learned two projects: tiktok project and IAM project, and summarized and practiced the CloudNative project and Go language. I learned a lot in the process.Myblog:http://nsddd.topopen in new window

[TOC]

开始

我们有了解到 RUSTful :

RESTful是一种设计和开发Web服务的软件架构风格，其全称为Representational State Transfer。RESTful架构风格强调使用统一资源标识符（URI）来表示资源，通过HTTP协议中的GET、POST、PUT、DELETE等方法对这些资源进行操作，以及通过HTTP响应返回数据或状态码来表示请求结果。

在RESTful架构中，每个URI代表一个资源，例如一个Web页面、一个文本文件或者一个数据库表。通过HTTP方法对这些资源进行操作时，客户端发送的HTTP请求中包含了对资源的标识以及所要执行的操作，服务端根据请求进行相应的处理，并返回HTTP响应以告知客户端操作结果。

RESTful架构风格的设计理念包括：资源的标识性、统一接口、无状态、可缓存性和分层系统等。它已经成为当前Web服务开发中的主流架构风格之一，被广泛应用于Web服务的设计和开发中。

为什么需要 Swagger

wagger是一个API文档自动生成工具，它可以帮助开发人员自动生成可交互的API文档和代码示例。使用Swagger可以大大提高API文档的可读性和易用性，同时也方便开发人员对API进行测试和调试。

学习Swagger可以从以下几个方面入手：

了解Swagger的基本概念和使用方法。可以阅读官方文档，了解Swagger的基本用法和常用特性，学习如何使用Swagger来定义API接口、生成文档和代码示例等。
学习Swagger的高级特性。除了基本的文档生成功能之外，Swagger还提供了一系列高级特性，如API安全认证、请求/响应验证、API版本管理等。学习这些特性可以帮助开发人员更好地使用Swagger来设计和开发API。
实践Swagger的使用。在学习Swagger的过程中，可以结合自己的项目来实践Swagger的使用，从而更好地掌握Swagger的使用方法和技巧。

为什么要学习Swagger呢？因为Swagger作为一种API文档自动生成工具，在现代的Web开发中使用广泛，可以大大提高API文档的可读性和易用性，减少API文档编写的工作量，同时也方便开发人员对API进行测试和调试。掌握Swagger的使用可以帮助开发人员更好地设计和开发API，提高开发效率和代码质量。

🌥️ 特性：

Swagger 是一套围绕 OpenAPI 规范构建的开源工具，可以设计、构建、编写和使用 REST API。Swagger 包含很多工具，其中主要的 Swagger 工具包括：
Swagger 编辑器：基于浏览器的编辑器，可以在其中编写 OpenAPI 规范，并实时预览 API 文档。https://editor.swagger.io 就是一个 Swagger 编辑器，你可以尝试在其中编辑和预览 API 文档。
Swagger UI：将 OpenAPI 规范呈现为交互式 API 文档，并可以在浏览器中尝试 API 调用。
Swagger Codegen：根据 OpenAPI 规范，生成服务器存根和客户端代码库，目前已涵盖了 40 多种语言。

Swagger 和 OpenAPI 的区别

我们在谈到 Swagger 时，也经常会谈到 OpenAPI。那么二者有什么区别呢？

OpenAPI是一种描述RESTful API的规范，而Swagger是一种实现OpenAPI规范的工具。

具体来说，OpenAPI规范定义了一种标准的API描述语言和数据格式，用于描述RESTful API的结构、参数、响应等信息。OpenAPI规范允许开发人员使用YAML或JSON格式来定义API的结构，使得API的描述更加清晰、规范、易于理解和使用。OpenAPI规范的定义可以作为API设计的指南，并且可以用于生成API文档和客户端代码。
而Swagger是一个实现了OpenAPI规范的工具，它提供了一系列功能，如API描述、API测试、API文档自动生成等。使用Swagger，开发人员可以通过GUI界面或者API描述文件来定义API，Swagger可以根据这些定义生成API文档、客户端代码、API测试等。Swagger可以帮助开发人员更好地理解API的结构、参数、响应等信息，提高API的开发效率和质量。
总的来说，OpenAPI和Swagger都是与RESTful API相关的工具和规范，OpenAPI规范定义了一种标准的API描述语言和数据格式，而Swagger是一种实现了OpenAPI规范的工具，可以帮助开发人员更好地理解、描述和使用RESTful API。

OpenAPI 是一个 API 规范，它的前身叫 Swagger 规范，通过定义一种用来描述 API 格式或 API 定义的语言，来规范 RESTful 服务开发过程，目前最新的 OpenAPI 规范是OpenAPI 3.0（也就是 Swagger 2.0 规范）。

OpenAPI 规范规定了一个 API 必须包含的基本信息，这些信息包括：

对 API 的描述，介绍 API 可以实现的功能。
每个 API 上可用的路径（/users）和操作（GET /users，POST /users）。
每个 API 的输入 / 返回的参数。
验证方法。
联系信息、许可证、使用条款和其他信息。

所以，你可以简单地这么理解：OpenAPI 是一个 API 规范，Swagger 则是实现规范的工具。

另外，要编写 Swagger 文档，首先要会使用 Swagger 文档编写语法，因为语法比较多，这里就不多介绍了，你可以参考 Swagger 官方提供的OpenAPI Specificationopen in new window来学习。

用 go-swagger 来生成 Swagger API 文档

在 Go 项目开发中，我们可以通过下面两种方法来生成 Swagger API 文档：

第一，如果你熟悉 Swagger 语法的话，可以直接编写 JSON/YAML 格式的 Swagger 文档。建议选择 YAML 格式，因为它比 JSON 格式更简洁直观。
第二，通过工具生成 Swagger 文档，目前可以通过swagopen in new window和go-swaggeropen in new window两个工具来生成。

对比这两种方法，直接编写 Swagger 文档，不比编写 Markdown 格式的 API 文档工作量小，我觉得不符合程序员“偷懒”的习惯。所以，本专栏我们就使用 go-swagger 工具，基于代码注释来自动生成 Swagger 文档。为什么选 go-swagger 呢？有这么几个原因：

go-swagger 比 swag 功能更强大： go-swagger 提供了更灵活、更多的功能来描述我们的 API。
使我们的代码更易读：如果使用 swag，我们每一个 API 都需要有一个冗长的注释，有时候代码注释比代码还要长，但是通过 go-swagger 我们可以将代码和注释分开编写，一方面可以使我们的代码保持简洁，清晰易读，另一方面我们可以在另外一个包中，统一管理这些 Swagger API 文档定义。
更好的社区支持：go-swagger 目前有非常多的 Github star 数，出现 Bug 的概率很小，并且处在一个频繁更新的活跃状态。

go-swagger

Github Project Addressopen in new window

你已经知道了，go-swagger 是一个功能强大的、高性能的、可以根据代码注释生成 Swagger API 文档的工具。

go-swagger为 Go 社区带来了一套完整的功能齐全、高性能的 API 组件，可与 Swagger API 配合使用：服务器、客户端和数据模型。

从 swagger 规范生成服务器
从 swagger 规范生成客户端
从 swagger 规范（alpha 阶段）生成 CLI（命令行工具）
支持 jsonschema 和 swagger 提供的大部分功能，包括多态性
从带注释的 go 代码生成 swagger 规范
使用 swagger 规范的附加工具
出色的定制功能，具有供应商扩展和可定制模板

我们对代码生成的关注点是生成惯用的、快速的 go 代码，它可以很好地与 golint、go vet 等配合使用。

⚠️ 这里需要注意，如果我们要对外提供 API 的 Go SDK，可以考虑使用 go-swagger 来生成客户端代码。但是我觉得 go-swagger 生成的服务端代码不够优雅，所以建议你自行编写服务端代码。

目前，有很多知名公司和组织的项目都使用了 go-swagger，例如 Moby、CoreOS、Kubernetes、Cilium 等。

项目状态

go-swagger现在功能已经完成并且已经稳定了它的 API。

大多数功能和构建块现在都处于稳定状态，具有丰富的 CI 测试集。

go-openapi 社区积极地继续为这个代码库带来修复和增强。

Swagger 上手

安装 Swagger 工具

go-swagger 通过 swagger 命令行工具来完成其功能，swagger 安装方法如下：

$ go get -u github.com/go-swagger/go-swagger/cmd/swagger

$ swagger version
version: v0.30.4
commit: (unknown, mod sum: "h1:cPrWLSXY6ZdcgfRicOj0lANg72TkTHz6uv/OlUdzO5U=")

swagger 命令行工具介绍

swagger 命令格式为swagger [OPTIONS] 。可以通过swagger -h查看 swagger 使用帮助。swagger 提供的子命令及功能见下表：

如何使用 swagger 命令生成 Swagger 文档？

go-swagger 通过解析源码中的注释来生成 Swagger 文档open in new window，go-swagger 的详细注释语法可参考官方文档。常用的有如下几类注释语法：

go-swagger 是一个用于生成 RESTful API 的工具，它支持使用 Swagger 规范（OpenAPI 规范）来定义 API 的接口和模型。在使用 go-swagger 时，我们可以使用特定的注释语法来定义 API 的信息和参数，以下是常用的几类注释语法和示例：

Swagger 注释

Swagger 注释用于定义 API 的信息，例如 API 的标题、描述、版本号 等。使用 swagger:xxx 的形式来注释，其中 xxx 表示注释的具体信息。

// swagger:operation GET /books/{id} getBook
//
// ---
// summary: Get book by ID
// description: Returns a single book by its ID.
// parameters:
// - name: id
//   in: path
//   description: ID of the book to retrieve
//   required: true
//   type: string
// responses:
//   "200":
//     description: Book information
//     schema:
//       "$ref": "#/definitions/Book"

Parameter 注释

Parameter 注释用于定义 API 接口的参数，包括参数的名称、类型、位置和描述等信息。使用 param 的形式来注释，其中 param 表示参数的具体信息。

// GetBookByID returns a single book by its ID.
//
// swagger:operation GET /books/{id} getBook
//
// ---
// summary: Get book by ID
// description: Returns a single book by its ID.
// parameters:
// - name: id
//   in: path
//   description: ID of the book to retrieve
//   required: true
//   type: string
//   format: uuid
//   param: query
// responses:
//   "200":
//     description: Book information
//     schema:
//       "$ref": "#/definitions/Book"

Response 注释

Response 注释用于定义 API 的响应数据结构和数据类型。使用 response 的形式来注释，其中 response 表示响应的具体信息。

// GetBookByID returns a single book by its ID.
//
// swagger:operation GET /books/{id} getBook
//
// ---
// summary: Get book by ID
// description: Returns a single book by its ID.
// parameters:
// - name: id
//   in: path
//   description: ID of the book to retrieve
//   required: true
//   type: string
//   format: uuid
// responses:
//   "200":
//     description: Book information
//     schema:
//       "$ref": "#/definitions/Book"
//       response: noContent
//   "404":
//     description: Book not found

解析注释生成 Swagger 文档

swagger generate 命令会找到 main 函数，然后遍历所有源码文件，解析源码中与 Swagger 相关的注释，然后自动生成 swagger.json/swagger.yaml 文件。

这一过程的示例代码为 gopractise-demo/swaggeropen in new window。目录下有一个 main.go 文件，定义了如下 API 接口：

package main

import (
    "fmt"
    "log"
    "net/http"

    "github.com/gin-gonic/gin"

    "github.com/marmotedu/gopractise-demo/swagger/api"
    // This line is necessary for go-swagger to find your docs!
    _ "github.com/marmotedu/gopractise-demo/swagger/docs"
)

var users []*api.User

func main() {
    r := gin.Default()
    r.POST("/users", Create)
    r.GET("/users/:name", Get)

    log.Fatal(r.Run(":5555"))
}

// Create create a user in memory.
func Create(c *gin.Context) {
    var user api.User
    if err := c.ShouldBindJSON(&user); err != nil {
        c.JSON(http.StatusBadRequest, gin.H{"message": err.Error(), "code": 10001})
        return
    }

    for _, u := range users {
        if u.Name == user.Name {
            c.JSON(http.StatusBadRequest, gin.H{"message": fmt.Sprintf("user %s already exist", user.Name), "code": 10001})
            return
        }
    }

    users = append(users, &user)
    c.JSON(http.StatusOK, user)
}

// Get return the detail information for a user.
func Get(c *gin.Context) {
    username := c.Param("name")
    for _, u := range users {
        if u.Name == username {
            c.JSON(http.StatusOK, u)
            return
        }
    }

    c.JSON(http.StatusBadRequest, gin.H{"message": fmt.Sprintf("user %s not exist", username), "code": 10002})
}

main 包中引入的 User struct 位于 gopractise-demo/swagger/api 目录下的user.goopen in new window文件：

// Package api defines the user model.
package api

// User represents body of User request and response.
type User struct {
    // User's name.
    // Required: true
    Name string `json:"name"`

    // User's nickname.
    // Required: true
    Nickname string `json:"nickname"`

    // User's address.
    Address string `json:"address"`

    // User's email.
    Email string `json:"email"`
}

// Required: true说明字段是必须的，生成 Swagger 文档时，也会在文档中声明该字段是必须字段。

为了使代码保持简洁，我们在另外一个 Go 包中编写带 go-swagger 注释的 API 文档。假设该 Go 包名字为 docs，在开始编写 Go API 注释之前，需要在 main.go 文件中导入 docs 包：

_ "github.com/marmotedu/gopractise-demo/swagger/docs"

通过导入 docs 包，可以使 go-swagger 在递归解析 main 包的依赖包时，找到 docs 包，并解析包中的注释。

在 gopractise-demo/swagger 目录下，创建 docs 文件夹：

$ mkdir docs
$ cd docs

在 docs 目录下，创建一个 doc.go 文件，在该文件中提供 API 接口的基本信息：


// Package docs awesome.
//
// Documentation of our awesome API.
//
//     Schemes: http, https
//     BasePath: /
//     Version: 0.1.0
//     Host: some-url.com
//
//     Consumes:
//     - application/json
//
//     Produces:
//     - application/json
//
//     Security:
//     - basic
//
//    SecurityDefinitions:
//    basic:
//      type: basic
//
// swagger:meta
package docs

Package docs 后面的字符串 awesome 代表我们的 HTTP 服务名。Documentation of our awesome API是我们 API 的描述。其他都是 go-swagger 可识别的注释，代表一定的意义。最后以swagger:meta注释结束。

编写完 doc.go 文件后，进入 gopractise-demo/swagger 目录，执行如下命令，生成 Swagger API 文档，并启动 HTTP 服务，在浏览器查看 Swagger：

$ swagger generate spec -o swagger.yaml
$ swagger serve --no-open -F=swagger --port 36666 swagger.yaml

2020/10/20 23:16:47 serving docs at http://localhost:36666/docs

-o：指定要输出的文件名。swagger 会根据文件名后缀.yaml 或者.json，决定生成的文件格式为 YAML 或 JSON。
–no-open：因为是在 Linux 服务器下执行命令，没有安装浏览器，所以使–no-open 禁止调用浏览器打开 URL。
-F：指定文档的风格，可选 swagger 和 redoc。我选用了 redoc，因为觉得 redoc 格式更加易读和清晰。
–port：指定启动的 HTTP 服务监听端口。

打开浏览器，访问http://localhost:36666/docs ，如下图所示：

如果我们想要 JSON 格式的 Swagger 文档，可执行如下命令，将生成的 swagger.yaml 转换为 swagger.json：

$ swagger generate spec -i ./swagger.yaml -o ./swagger.json

接下来，我们就可以编写 API 接口的定义文件（位于gopractise-demo/swagger/docs/user.goopen in new window文件中）：


package docs

import (
    "github.com/marmotedu/gopractise-demo/swagger/api"
)

// swagger:route POST /users user createUserRequest
// Create a user in memory.
// responses:
//   200: createUserResponse
//   default: errResponse

// swagger:route GET /users/{name} user getUserRequest
// Get a user from memory.
// responses:
//   200: getUserResponse
//   default: errResponse

// swagger:parameters createUserRequest
type userParamsWrapper struct {
    // This text will appear as description of your request body.
    // in:body
    Body api.User
}

// This text will appear as description of your request url path.
// swagger:parameters getUserRequest
type getUserParamsWrapper struct {
    // in:path
    Name string `json:"name"`
}

// This text will appear as description of your response body.
// swagger:response createUserResponse
type createUserResponseWrapper struct {
    // in:body
    Body api.User
}

// This text will appear as description of your response body.
// swagger:response getUserResponse
type getUserResponseWrapper struct {
    // in:body
    Body api.User
}

// This text will appear as description of your error response body.
// swagger:response errResponse
type errResponseWrapper struct {
    // Error code.
    Code int `json:"code"`

    // Error message.
    Message string `json:"message"`
}

user.go 文件说明：

swagger:route：swagger:route代表 API 接口描述的开始，后面的字符串格式为HTTP方法 URL Tag ID。可以填写多个 tag，相同 tag 的 API 接口在 Swagger 文档中会被分为一组。ID 是一个标识符，swagger:parameters是具有相同 ID 的swagger:route的请求参数。swagger:route下面的一行是该 API 接口的描述，需要以英文点号为结尾。responses:定义了 API 接口的返回参数，例如当 HTTP 状态码是 200 时，返回 createUserResponse，createUserResponse 会跟swagger:response进行匹配，匹配成功的swagger:response就是该 API 接口返回 200 状态码时的返回。
swagger:response：swagger:response定义了 API 接口的返回，例如 getUserResponseWrapper，关于名字，我们可以根据需要自由命名，并不会带来任何不同。getUserResponseWrapper 中有一个 Body 字段，其注释为// in:body，说明该参数是在 HTTP Body 中返回。swagger:response之上的注释会被解析为返回参数的描述。api.User 自动被 go-swagger 解析为Example Value和Model。我们不用再去编写重复的返回字段，只需要引用已有的 Go 结构体即可，这也是通过工具生成 Swagger 文档的魅力所在。
swagger:parameters：swagger:parameters定义了 API 接口的请求参数，例如 userParamsWrapper。userParamsWrapper 之上的注释会被解析为请求参数的描述，// in:body代表该参数是位于 HTTP Body 中。同样，userParamsWrapper 结构体名我们也可以随意命名，不会带来任何不同。swagger:parameters之后的 createUserRequest 会跟swagger:route的 ID 进行匹配，匹配成功则说明是该 ID 所在 API 接口的请求参数。

进入 gopractise-demo/swagger 目录，执行如下命令，生成 Swagger API 文档，并启动 HTTP 服务，在浏览器查看 Swagger：

$ swagger generate spec -o swagger.yaml
$ swagger serve --no-open -F=swagger --port 36666 swagger.yaml
2020/10/20 23:28:30 serving docs at http://localhost:36666/docs

打开浏览器，访问 http://localhost:36666/docs ，如下图所示：

上面我们生成了 swagger 风格的 UI 界面，我们也可以使用 redoc 风格的 UI 界面，如下图所示：

go-swagger 其他常用功能介绍

上面，我介绍了 swagger 最常用的 generate、serve 命令，关于 swagger 其他有用的命令，这里也简单介绍一下。

对比 Swagger 文档


$ swagger diff -d change.log swagger.new.yaml swagger.old.yaml
$ cat change.log

BREAKING CHANGES:
=================
/users:post Request - Body.Body.nickname.address.email.name.Body : User - Deleted property
compatibility test FAILED: 1 breaking changes detected

生成服务端代码

我们也可以先定义 Swagger 接口文档，再用 swagger 命令，基于 Swagger 接口文档生成服务端代码。假设我们的应用名为 go-user，进入 gopractise-demo/swagger 目录，创建 go-user 目录，并生成服务端代码：

$ mkdir go-user
$ cd go-user
$ swagger generate server -f ../swagger.yaml -A go-user

上述命令会在当前目录生成 cmd、restapi、models 文件夹，可执行如下命令查看 server 组件启动方式：

$ go run cmd/go-user-server/main.go -h

生成客户端代码

在 go-user 目录下执行如下命令：

$ swagger generate client -f ../swagger.yaml -A go-user

上述命令会在当前目录生成 client，包含了 API 接口的调用函数，也就是 API 接口的 Go SDK。

验证 Swagger 文档是否合法

$ swagger validate swagger.yaml
2020/10/21 09:53:18
The swagger spec at "swagger.yaml" is valid against swagger specification 2.0

合并 Swagger 文档

$ swagger mixin swagger_part1.yaml swagger_part2.yaml

IAM Swagger 文档

IAM 的 Swagger 文档定义在 iam/api/swagger/docs目录下，遵循 [go-swagger]规范进行定义。

iam/api/swagger/docs/doc.goopen in new window文件定义了更多 Swagger 文档的基本信息，比如开源协议、联系方式、安全认证等。

更详细的定义，你可以直接查看 iam/api/swagger/docs 目录下的 Go 源码文件。

为了便于生成文档和启动 HTTP 服务查看 Swagger 文档，该操作被放在 Makefile 中执行（位于iam/scripts/make-rules/swagger.mk文件中）：

.PHONY: swagger.run    
swagger.run: tools.verify.swagger    
  @echo "===========> Generating swagger API docs"    
  @swagger generate spec --scan-models -w $(ROOT_DIR)/cmd/genswaggertypedocs -o $(ROOT_DIR)/api/swagger/swagger.yaml    
    
.PHONY: swagger.serve    
swagger.serve: tools.verify.swagger    
  @swagger serve -F=redoc --no-open --port 36666 $(ROOT_DIR)/api/swagger/swagger.yaml

Makefile 文件说明：

tools.verify.swagger：检查 Linux 系统是否安装了 go-swagger 的命令行工具 swagger，如果没有安装则运行 go get 安装。
swagger.run：运行 swagger generate spec 命令生成 Swagger 文档 swagger.yaml，运行前会检查 swagger 是否安装。 --scan-models 指定生成的文档中包含带有 swagger:model 注释的 Go Models。-w 指定 swagger 命令运行的目录。
swagger.serve：运行 swagger serve 命令打开 Swagger 文档 swagger.yaml，运行前会检查 swagger 是否安装。

在 iam 源码根目录下执行如下命令，即可生成并启动 HTTP 服务查看 Swagger 文档：

$ make swagger
$ make serve-swagger
2020/10/21 06:45:03 serving docs at http://localhost:36666/docs

打开浏览器，打开http://x.x.x.x:36666/docs查看 Swagger 文档，x.x.x.x 是服务器的 IP 地址，如下图所示：

IAM 的 Swagger 文档，还可以通过在 iam 源码根目录下执行go generate ./...命令生成，为此，我们需要在 iam/cmd/genswaggertypedocs/swagger_type_docs.go 文件中，添加//go:generate注释。如下图所示：

总结

在做 Go 服务开发时，我们要向前端或用户提供 API 文档，手动编写 API 文档工作量大，也难以维护。所以，现在很多项目都是自动生成 Swagger 格式的 API 文档。提到 Swagger，很多开发者不清楚其和 OpenAPI 的区别，所以我也给你总结了：OpenAPI 是一个 API 规范，Swagger 则是实现规范的工具。

Go-Swagger是一个用于构建RESTful API服务的工具，它能够自动生成Swagger文档和客户端代码，并提供了丰富的API开发工具和框架。下面是对Go-Swagger的总结：

优点

Go-Swagger的最大优点在于其能够自动生成Swagger文档和客户端代码。Swagger是一个用于描述RESTful API的标准规范，它定义了API的各种细节，如请求参数、返回值、错误码等等。使用Go-Swagger可以自动生成Swagger文档，使得API的文档编写更加快速和简便。同时，Go-Swagger还可以生成各种客户端代码，包括Go、Python、Java等等，极大地方便了API的调用。

除了自动生成Swagger文档和客户端代码外，Go-Swagger还提供了许多API开发工具和框架，包括验证器、序列化器、路由器等等。这些工具和框架可以让API的开发更加高效和方便，大大提升了开发效率。

缺点

尽管Go-Swagger具有许多优点，但也存在一些缺点。首先，Go-Swagger的学习曲线比较陡峭，需要花费一定的时间和精力去学习和掌握。此外，由于Go-Swagger是一个比较新的工具，其社区相对较小，缺少一些成熟的解决方案和插件。

应用场景

Go-Swagger适用于需要快速构建RESTful API服务的应用场景。使用Go-Swagger可以快速生成Swagger文档和客户端代码，减少了API文档编写和客户端代码开发的工作量，同时提供了丰富的API开发工具和框架，大大提高了开发效率。此外，Go-Swagger还支持多种编程语言，适用于不同的开发团队和开发环境。

总结

综上所述，Go-Swagger是一个非常实用的API开发工具，能够快速生成Swagger文档和客户端代码，提供了丰富的API开发工具和框架，适用于快速构建RESTful API服务的应用场景。虽然Go-Swagger的学习曲线比较陡峭，但通过学习和掌握，可以大大提高API的开发效率。

END 链接

Ⓜ️回到目录🏠
🫵参与贡献💞❤️‍🔥💖open in new window)

# 第10节 如何生成 Swagger API 文档

# 开始

# 为什么需要 Swagger

# Swagger 和 OpenAPI 的区别

# 用 go-swagger 来生成 Swagger API 文档

# go-swagger

# 项目状态

# Swagger 上手

# 安装 Swagger 工具

# swagger 命令行工具介绍

# 如何使用 swagger 命令生成 Swagger 文档？

# Swagger 注释

# Parameter 注释

# Response 注释

# 解析注释生成 Swagger 文档

# go-swagger 其他常用功能介绍

# 对比 Swagger 文档

# 生成服务端代码

# 生成客户端代码

# 验证 Swagger 文档是否合法

# 合并 Swagger 文档

# IAM Swagger 文档

# 总结

# END 链接