这是一个创建于 1585 天前的主题，其中的信息可能已经有所发展或是发生改变。
之前我试过纯粹用编辑 API 的软件写 API 文档，但是发现坚持不下去，每个 API 返回值啥的都要我一个个写好，而且接口改动之后往往就忘记了改 API 文档，毕竟是在两个地方的，要开两个软件。
用了 swagger 感觉会轻松很多，只需要定义传入参数就行了，传出参数也只需要简单描述一下每个字段是干啥的，返回值直接就动态生成了。注释就在代码里，总能比上面这种方法不容易忘吧
但是现在写着写着又感觉不爽了，遇到复杂的接口，参数很多，注释比代码都长有时候，而且 idea 的 swagger 注释和其他注释一样黄黄的看着人眼都要晃了，突然想到如果能把 swagger 的注释颜色改成普通注释颜色应该会舒服很多，不知道可不可行。
 | 1 liuxu 2021-08-15 00:46:16 +08:00 不想写了，现在都是用 postman 做接口文档 |
 | 2 yitingbai 2021-08-15 00:48:52 +08:00 swagger 不好的地方太多了, 有些参数并不想暴露给前端, 另外注解写的太多, 代码又臭又长, 但是除了这个又有啥好办法呢, 我更不想再去维护一份文档 |
 | 3 Philippa 2021-08-15 00:49:14 +08:00 via iPhone 现在一般用 grpc 自动生成不用写的就定一下 path 和 method 就完事了，要么是 graphql 也有 playground 。swagger 要是手写的话还不如不要了 |
 | 4 sutra 2021-08-15 00:49:51 +08:00 |
 | 5 xuanbg 2021-08-15 04:53:34 +08:00  1 swagger 生成的文档不是自己的文档，所以从来不用。 |
 | 6 shellic 2021-08-15 09:07:58 +08:00 直接导出 postman 了 |
 | 7 abcbuzhiming 2021-08-15 09:38:32 +08:00 到目前为止，swagger 这种代码和文档直接关联的做法还是最佳实践，单独写文档的最大问题，就是你一定要分出人力监督写代码的人务必更新文档，尤其在协作开发时这个问题非常突出 |
 | 8 orcusfox 2021-08-15 09:47:49 +08:00 via iPhone Swagger 选择 openapi 3.0 模式，生成的文档可以整个导入 postman, insomnia 之类的客户端，不挺香的 |
 | 10 chendy 2021-08-15 11:09:36 +08:00 swagger 是 code first 不是 api first 最好还是有独立的 api 管控 |
 | 11 wangbenjun5 2021-08-15 12:04:44 +08:00 阿里都是特别 low 的做法，人工手动整理到语雀文档上。。。也没个标准规范！如果时间充分的情况下我觉得人工整理也还行吧，swagger 就是省事 |
 | 12 Rwing 2021-08-15 13:15:44 +08:00 还好吧，只是代码的注释而已，就算不用 swagger 也要写，所以没什么不舒服的感觉 |
 | 13 abigeater 2021-08-15 15:18:21 +08:00 不喜欢写 swagger 觉得很“笨重”，还不如用 postman 调试时顺便生成的文档。 |
 | 14 EscYezi 2021-08-15 19:25:57 +08:00 via iPhone 还是要用的，前后端联调接口给个链接就行，有效降低沟通成本，写很多注解也就麻烦那一次，之后维护方便点。 参数多的话直接包一个实体类，每个字段上写 ApiModelProperty 注解 |
 | 15 talen666 2021-08-16 00:22:04 +08:00 用的 YAPI |
 | 16 lixm 2021-08-16 08:58:25 +08:00 openapi 规范的文档， 难道不是用来生成代码的吗？ 一个模型上百个字段， 一个个手写？ |
 | 17 MarioLuo 2021-09-28 23:44:42 +08:00 via Android 用 Yapi X 插件，从 Javadoc 中一键生成文档: https://github.com/jetplugins/yapix |
Select Language