17 | API 文档：如何生成 Swagger API 文档 ？
该思维导图由 AI 生成，仅供参考
Swagger 介绍
荧光笔
直线
曲线- 深入了解
- 翻译
- 解释
- 总结
本文介绍了如何使用go-swagger工具生成API文档，并详细介绍了Swagger的作用、主要工具以及与OpenAPI的区别。作者重点介绍了使用go-swagger生成Swagger API文档的步骤，并推荐了go-swagger的原因。文章还介绍了常用的注释语法和go-swagger的其他常用功能，如对比Swagger文档、生成服务端和客户端代码，以及验证Swagger文档是否合法等。通过本文，读者可以了解到Swagger的重要性以及如何利用go-swagger工具来简化API文档的生成过程，提高开发效率。此外，文章还提到了在Go服务开发中使用go-swagger生成Swagger格式的API文档的实际操作步骤，并提出了课后练习，鼓励读者尝试在自己的项目中应用所学知识。文章内容详实，适合开发人员快速了解并应用于实际项目中。
《Go 语言项目开发实战》，新⼈⾸单¥68
全部留言(18)
- 最新
- 精选
daz2yy一点想法，在小团队里，其实也没那么规范，能简单就简单点，目前用的是 Postman 生成的文档，考虑的点： 1. 一方面程序员自己调试接口必然会用到接口调用工具，postman大家也比较熟悉； 2. 另一方面开发完之后，它能直接生成在线文档，不用重新去定义文档使用的 API 的字段、结构体等，感觉会方便很多，而且能实时同步修改（接口有变动可以同步反映到文档上，不需要二次修改 api 文档，减少人为的错误） 请教下老师对两者的看法，主要是我觉得写 swagger 接口注释这个工作比较繁琐，另外需要特意去维护它，容易出现代码改了但是文档未改的情况；或者说老师这边有什么好的实践经验。 FYI：Makefile 说明那里有个 Models 写成了 Modles作者回复: 文档怎么编写，这里其实没有一个统一的、标准的规范，因为不同团队对API文档的要求、对使用工具的选择都不一样。 这一讲介绍的方法，仅供参考。具体使用哪种，你们可以参考这一讲介绍的方法， 再结合自己的实际需求和情况，进行调研之后，再做选择。 如果你们觉得postman、或者一些在线工具能满足你们的需求，其实我觉得可能要不用swagger更好些，毕竟可视化、而且真的很方便、效率很高。 感谢反馈。
2021-07-0557
遇见@z看着好麻烦，我们公司自己写的框架通过扫描ast语法树生成openapi，代码即文档作者回复: 强，这个没有固定的方法，可以根据需要自己选择。这是个好方法，后面我看下怎么补下这种方式
2021-07-0846
helloworld思考题可能的好处：1. 方便和项目根路径下的帮助文档目录docs做区分；2. 路径层次清晰辨认功能；3. 方便启api文档的http服务？作者回复: 说的很好。再补充下：放在api目录下，说明这个是api的定义文件。API文档聚合在一个目录下，后期维护，查看都很方便
2021-07-034
先听swagger可以通过扫描源码生成文档。但是后端往往需要在编码之前就提供接口文档。貌似有些矛盾作者回复: 所以这里，可以选择直接编写swagger格式的API接口文档。
2021-07-2122- Geek_5baa01需求确认了后,后台首先应该写swagger 提供给前端开发, 相互不影响, 按照你这个套路, 是不是得后端开发完了在让前端搞
作者回复: 不是，要先写swagger文档。这里根据注解来生成swagger文档，不太建议用了。或者先把伪代码写出来。 重点结论：建议直接编写swagger文档。
2022-11-14归属地：广东1 
NULL"目前最新的 OpenAPI 规范是OpenAPI 3.0（也就是 Swagger 2.0 规范）" 这里错了啊, 现在最新的规范是2021年2月16日发布的 OpenAPI 3.1.0, 而且 OpenAPI 3.0 != Swagger 2.0 OpenAPI有三个版本 Swagger 2.0, OpenAPI 3.0.x, OpenAPI 3.1.0 详见: https://swagger.io/blog/news/whats-new-in-openapi-3-0/ https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0作者回复: 我联系小编更正下，感谢反馈~
2022-07-30归属地：广东1
咖梵冰雨这个demo运行会有跨域问题？这个本地咋解决，我gin加了中间件运行跨域好像不管用作者回复: 不会有跨域的问题。跨域： 浏览器访问的域名和浏览器发送请求的域名不一致，会触发浏览器的跨域请求。
2021-11-0921- typesswagger文档可以手动编写，也可以通过工具解析注释生成文档。 说明关于swagger 文档产生了2中开发模式： 1. 手动编写swagger 文档，可以通过文档生成代码 2. 先编写代码，添加swagger规范的注释，生成文档。 请问一般开发中，使用哪种swagger模式？（我看kubernetes中的api doc不是通过代码生成的）
作者回复: 哪种都有，根据需要选择吧，如果需要并行开发，可以先编写swagger，否则可以根据喜好选择2.
2021-07-3121 
Jone_乔泓恺swagger generate 命令会找到 main 函数，然后遍历所有的源代码，解析源码中与 Swagger 相关的注释，然后自动生成 swagger.json/swagger.yaml 文件； version: v0.29.0 不适用了吧？作者回复: 我check下
2022-07-06归属地：广东
yangchnet请问老师怎么看待“protoc-gen-openapiv2”这个工具，使用proto文件定义了接口出入参后可以直接生成swagger文档，不用再手动去编写。是不是比文中这种去手动编写的方便一点呢。作者回复: 我比较喜欢手动编写吧。 openapi这类工具，能帮助自动生成文档、代码等。比较规范，但是编写文档的工作量跟手动编写没啥区别
2022-02-05
