• daz2yy
    2021-07-05
    一点想法，在小团队里，其实也没那么规范，能简单就简单点，目前用的是 Postman 生成的文档，考虑的点： 1. 一方面程序员自己调试接口必然会用到接口调用工具，postman大家也比较熟悉； 2. 另一方面开发完之后，它能直接生成在线文档，不用重新去定义文档使用的 API 的字段、结构体等，感觉会方便很多，而且能实时同步修改（接口有变动可以同步反映到文档上，不需要二次修改 api 文档，减少人为的错误） 请教下老师对两者的看法，主要是我觉得写 swagger 接口注释这个工作比较繁琐，另外需要特意去维护它，容易出现代码改了但是文档未改的情况；或者说老师这边有什么好的实践经验。 FYI：Makefile 说明那里有个 Models 写成了 Modles

    作者回复: 文档怎么编写，这里其实没有一个统一的、标准的规范，因为不同团队对API文档的要求、对使用工具的选择都不一样。 这一讲介绍的方法，仅供参考。具体使用哪种，你们可以参考这一讲介绍的方法， 再结合自己的实际需求和情况，进行调研之后，再做选择。 如果你们觉得postman、或者一些在线工具能满足你们的需求，其实我觉得可能要不用swagger更好些，毕竟可视化、而且真的很方便、效率很高。 感谢反馈。

    共 5 条评论
    7
  • 遇见@z
    2021-07-08
    看着好麻烦，我们公司自己写的框架通过扫描ast语法树生成openapi，代码即文档

    作者回复: 强，这个没有固定的方法，可以根据需要自己选择。这是个好方法，后面我看下怎么补下这种方式

    共 4 条评论
    6
  • helloworld
    2021-07-03
    思考题可能的好处：1. 方便和项目根路径下的帮助文档目录docs做区分；2. 路径层次清晰辨认功能；3. 方便启api文档的http服务？

    作者回复: 说的很好。再补充下：放在api目录下，说明这个是api的定义文件。API文档聚合在一个目录下，后期维护，查看都很方便

    
    4
  • 先听
    2021-07-21
    swagger可以通过扫描源码生成文档。但是后端往往需要在编码之前就提供接口文档。貌似有些矛盾

    作者回复: 所以这里，可以选择直接编写swagger格式的API接口文档。

    共 2 条评论
    2
  • Geek_5baa01
    2022-11-14 来自广东
    需求确认了后,后台首先应该写swagger 提供给前端开发, 相互不影响, 按照你这个套路, 是不是得后端开发完了在让前端搞

    作者回复: 不是，要先写swagger文档。这里根据注解来生成swagger文档，不太建议用了。或者先把伪代码写出来。 重点结论：建议直接编写swagger文档。

    
    1
  • NULL
    2022-07-30 来自广东
    "目前最新的 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

    作者回复: 我联系小编更正下，感谢反馈~

    
    1
  • 咖梵冰雨
    2021-11-09
    这个demo运行会有跨域问题？这个本地咋解决，我gin加了中间件运行跨域好像不管用

    作者回复: 不会有跨域的问题。跨域： 浏览器访问的域名和浏览器发送请求的域名不一致，会触发浏览器的跨域请求。

    共 2 条评论
    1
  • types
    2021-07-31
    swagger文档可以手动编写，也可以通过工具解析注释生成文档。 说明关于swagger 文档产生了2中开发模式： 1. 手动编写swagger 文档，可以通过文档生成代码 2. 先编写代码，添加swagger规范的注释，生成文档。 请问一般开发中，使用哪种swagger模式？（我看kubernetes中的api doc不是通过代码生成的）

    作者回复: 哪种都有，根据需要选择吧，如果需要并行开发，可以先编写swagger，否则可以根据喜好选择2.

    共 2 条评论
    1
  • Jone_乔泓恺
    2022-07-06 来自广东
    swagger generate 命令会找到 main 函数，然后遍历所有的源代码，解析源码中与 Swagger 相关的注释，然后自动生成 swagger.json/swagger.yaml 文件； version: v0.29.0 不适用了吧？

    作者回复: 我check下

    
    
  • yangchnet
    2022-02-05
    请问老师怎么看待“protoc-gen-openapiv2”这个工具，使用proto文件定义了接口出入参后可以直接生成swagger文档，不用再手动去编写。是不是比文中这种去手动编写的方便一点呢。

    作者回复: 我比较喜欢手动编写吧。 openapi这类工具，能帮助自动生成文档、代码等。比较规范，但是编写文档的工作量跟手动编写没啥区别

    
    