大家现在还用 swagger 生成 API 文档吗

[shadowfish0]

之前我试过纯粹用编辑 API 的软件写 API 文档，但是发现坚持不下去，每个 API 返回值啥的都要我一个个写好，而且接口改动之后往往就忘记了改 API 文档，毕竟是在两个地方的，要开两个软件。

用了 swagger 感觉会轻松很多，只需要定义传入参数就行了，传出参数也只需要简单描述一下每个字段是干啥的，返回值直接就动态生成了。注释就在代码里，总能比上面这种方法不容易忘吧

但是现在写着写着又感觉不爽了，遇到复杂的接口，参数很多，注释比代码都长有时候，而且 idea 的 swagger 注释和其他注释一样黄黄的看着人眼都要晃了，突然想到如果能把 swagger 的注释颜色改成普通注释颜色应该会舒服很多，不知道可不可行。

[liuxu]

不想写了，现在都是用 postman 做接口文档

[yitingbai]

swagger 不好的地方太多了, 有些参数并不想暴露给前端, 另外注解写的太多, 代码又臭又长, 但是除了这个又有啥好办法呢, 我更不想再去维护一份文档

[Philippa]

现在一般用 grpc 自动生成不用写的就定一下 path 和 method 就完事了，要么是 graphql 也有 playground 。swagger 要是手写的话还不如不要了

[sutra]

RESTful 的话用 enunciate https://github.com/stoicflame/enunciate

GraphQL 的话，playground 也都能显示文档。

[xuanbg]

swagger 生成的文档不是自己的文档，所以从来不用。

[shellic]

直接导出 postman 了

[abcbuzhiming]

到目前为止，swagger 这种代码和文档直接关联的做法还是最佳实践，单独写文档的最大问题，就是你一定要分出人力监督写代码的人务必更新文档，尤其在协作开发时这个问题非常突出

[napsterwu]

Swagger 选择 openapi 3.0 模式，生成的文档可以整个导入 postman, insomnia 之类的客户端，不挺香的

[liaojl]

@yitingbai 某些参数不想暴露给前端，可以在字段注解上加 ignore=true

[chendy]

swagger 是 code first 不是 api first
最好还是有独立的 api 管控

[wangbenjun5]

阿里都是特别 low 的做法，人工手动整理到语雀文档上。。。也没个标准规范！如果时间充分的情况下我觉得人工整理也还行吧，swagger 就是省事

[Rwing]

还好吧，只是代码的注释而已，就算不用 swagger 也要写，所以没什么不舒服的感觉

[abigeater]

不喜欢写 swagger 觉得很“笨重”，还不如用 postman 调试时顺便生成的文档。

[EscYezi]

还是要用的，前后端联调接口给个链接就行，有效降低沟通成本，写很多注解也就麻烦那一次，之后维护方便点。
参数多的话直接包一个实体类，每个字段上写 ApiModelProperty 注解

[talen666]

用的 YAPI

[lixm]

openapi 规范的文档， 难道不是用来生成代码的吗？ 一个模型上百个字段， 一个个手写？

[MarioLuo]

用 Yapi X 插件，从 Javadoc 中一键生成文档: https://github.com/jetplugins/yapix