这是一个创建于 1206 天前的主题，其中的信息可能已经有所发展或是发生改变。
之前我试过纯粹用编辑 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
napsterwu 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