这是一个创建于 1317 天前的主题，其中的信息可能已经有所发展或是发生改变。
现在大家更多的是直接在 showdoc/yapi 等工具里直接写 API，还是用 swagger(openapi)写注解？ 感觉从工程角度是不是应该写注解规范点，可是看了看 openapi 的语法，好像有点繁琐，写一个接口文档要占据巨大的篇幅，又不太适合？
 |
1
mopland 2021-04-23 14:10:35 +08:00
|
 |
2
dzdh 2021-04-23 14:14:10 +08:00
markdown
[TOC] # 约定 ## 接口地址 base uri: sandbox https production https.... ## 名词解释 xx : 是 xxxx 表示 xxxx 从哪来 xxxx 特殊情况有几种应该怎么办会不会变怎么变 # 接口 ## 公共参数 table name, 必传?, 默认值, 备注 `METHOD|METHOD2 如果有 /path` table name,必传?,默认值,备注 # 附录 ## 1 ## 2 ## 3 |
 |
3
Rwing 2021-04-23 14:17:22 +08:00  3
相信我，如果是在另外的工具里写，那么 90%的程序员都不会及时更新的，导致文档滞后或错误。
所以最佳做法一定是在代码里写 |
 |
4
lplk 2021-04-23 14:18:10 +08:00 via Android
我目前用 openapi ，我觉得这个挺好
|
 |
5
jjwjiang 2021-04-23 16:02:09 +08:00
swagger 不是自带通过注解生成 openapi 文档的功能吗
|
Select Language