关于 API 文档撰写方式

[jry]

现在大家更多的是直接在 showdoc/yapi 等工具里直接写 API，还是用 swagger(openapi)写注解？ 感觉从工程角度是不是应该写注解规范点，可是看了看 openapi 的语法，好像有点繁琐，写一个接口文档要占据巨大的篇幅，又不太适合？

[mopland]

我们是定制一套规范，都按规范来书写，同时框架自动解析生成文档，接口校验、权限验证都使用同一套方案。

http://notes.veryide.com/gateway.md

[dzdh]

markdown

[TOC]

# 约定
## 接口地址
base uri: sandbox https production https....
## 名词解释
xx :
是 xxxx 表示 xxxx 从哪来 xxxx 特殊情况有几种应该怎么办会不会变怎么变

# 接口
## 公共参数
table name, 必传?, 默认值, 备注

`METHOD|METHOD2 如果有 /path`
table name,必传?,默认值,备注

# 附录
## 1
## 2
## 3

[Rwing]

相信我，如果是在另外的工具里写，那么 90%的程序员都不会及时更新的，导致文档滞后或错误。
所以最佳做法一定是在代码里写

[lplk]

我目前用 openapi ，我觉得这个挺好

[jjwjiang]

swagger 不是自带通过注解生成 openapi 文档的功能吗

[jry]

那就 openapi 吧
@Rwing 我觉得你这点说的很有道理

[jry]

@jjwjiang 就是觉得注解设计的有点繁琐，不够简洁？