23丨管理接口：如何集成swagger自动生成文件？【1】.pdf资源-CSDN文库

版权申诉

98 浏览量 2024-12-13 14:30:15 上传评论收藏 9.87MB PDF 举报

资源推荐

资源详情

资源评论

2021/11/19 23｜管理接口：如何集成swagger自动生成文件？

https://time.geekbang.org/column/article/435582 1/22

23｜管理接口：如何集成swagger自动生成文件？

2021-11-08 叶剑峰

《手把手带你写一个Web框架》

课程介绍

讲述：叶剑峰

时长 18:52 大小 17.29M



你好，我是轩脉刃。

不管你是前端页面开发，还是后端服务开发，你一定经历过前后端联调的场景，前后端联

调最痛苦的事情，莫过于没有完善的接口文档、没有可以调用调试的接口返回值了，所以

一般都会采用形如 Postman 这样的第三方工具，来进行接口的调用和联调。

但是这一节课，我们要做的事情，就是为自己的 Web 应用集成 swagger，使用 swagger

自动生成一个可以查看接口、可以调用执行的页面。

swagger







下载APP 

海量资源：666java.com

2021/11/19 23｜管理接口：如何集成swagger自动生成文件？

https://time.geekbang.org/column/article/435582 2/22

说到 swagger，可能有的同学还比较陌生，我来简要介绍一下。swagger 框架在 2009 年

启动，之前是 Reverb 公司内部开发的一个项目，他们的工程师在与第三方调试 REST 接

口的过程中，为了解决大量的接口与文档问题，就设计了 swagger 这个项目。

项目最终成型的方案是，先设计一个 JSON 规则，开发工程师把所有服务接口按照这种规

则来写成一个 JSON 文件，这个 JSON 文件可以直接生成一个交互式 UI，可以提供调用

者查看、调用调试。

swagger 的应用是非常广泛的。非常多的开源项目在提供对外接口的时候都使用 swagger

来进行描述。比如目前最火的 Kubernetes 项目，每次在发布版本的时候，都会在项目根

目录上，带上符合 swagger 规则的 JSON 文件，用来向使用者提供内部接口。

swagger 的产品有两类。

一个是前面说的 JSON 规则，就是 OpenAPI 的文档，它说明了我们要写一个接口说明文

档的每个字段含义和要求。

OpenAPI 的规则也是有版本的，目前最新版本是 3.0，但是 3.0 版本目前市场上相应的配

套支持还不成熟，比如 Golang 版本的 SDK 库 spec还不支持。目前市面上对

OpenAPI2.0 的支持还是最全的。所以我们的 hade 框架就使用 swagger2.0 版本。

swagger 的另外一类产品是工具，包括 swagger-ui、swagger-editor 和 swagger-

codegen。

 swagger-editor提供一个开源网站，在线编辑 swagger 文件。 swagger-codegen提

供一个 Java 命令行工具，通过 swagger 文件生成 client 端代码。而 swagger-ui，通

过提供一个开源网站，将 swagger 接口在线展示出来，并且可以让调用者查看、调试。我

们的目标是生成一个可以查看接口，进行调用调试的页面，所以要将 swagger-ui 集成进

hade 框架。

命令设计

了解了 swagger，结合框架，我们照例先思考下希望如何使用它。

海量资源：666java.com

2021/11/19 23｜管理接口：如何集成swagger自动生成文件？

https://time.geekbang.org/column/article/435582 3/22

按照 swagger 的定义，我们应该在业务项目中维护一个 JSON 文件，这个文件描述了这个

业务的所有接口。但是你想过没有，随着项目的接口数越来越大，维护 swagger 的

JSON 描述文档本身，就是一个很大很繁杂的工作量。

由于每个接口在代码开发的时候，我们都会有注释，而更新代码的时候，我们是会去更新

注释的。所以能不能有一个方法，通过代码的注释，自动生成这个 JSON 文件呢？

好，这个就是我们希望定义的一个 swagger 命令，./hade swagger gen ，能通过注释

生成 swagger.json 文件。

但是考虑具体的实现设计，怎么用 Golang 的代码，注释生成 swagger.json 呢？既然

swagger.json 是有一定的规则的，那么注释的写法也是有一定规则的吧？是的。目前有一

个最流行的将 Golang 注释转化为 swagger.json 的开源项目 swag。

swag 项目

这个 swag 项目是 MIT 协议，目前已经有 4.9k 个 star 了。它的用法和我们想要的一样，

生成 swagger.json 分三步：

步骤很简单，不过第一步怎么写 swag 的注释说明文档，是使用这个技术必须要学习的一

个知识，这个的学习确实是有些门槛的，需要熟读对应的说明文档才能写出比较好的注

释。这里我们用一个例子来讲解我在编写代码的时候常用的一些字段，供你参考。

在 API 接口中编写注释。注释的详细写法需要参考 说明文档。

下载 swag 工具或者安装 swag 库

使用工具或者库将指定代码生成 swagger.json

 复制代码

1

2

3

4

5

6

7

8

9

// Demo2 for godoc

// @Summary 获取所有学生

// @Description 获取所有学生，不进行分页

// @Produce json

// @Tags demo

// @Success 200 {array} []UserDTO

// @Router /demo/demo2 [get]

func (api *DemoApi) Demo2(c *gin.Context) {

demoProvider := c.MustMake(demoService.DemoKey).(demoService.IService)

海量资源：666java.com

剩余21页未读，继续阅读

内容反馈

版权申诉

希希分享

粉丝: 6989
资源: 3837

最新资源

资源上传下载、课程学习等过程中有任何疑问或建议，欢迎提出宝贵意见哦~我们会及时处理！点击此处反馈

feedback-tip