很多其他产品有过注释生成文档的做法了,但是感觉格式稍微有些复杂,编写不够方便,代码污染
注释格式经过了很长时间的思考,怎样才能更优雅方便?
最终格式如下图,如有不爽的地方,请各位使劲喷:
@easydoc api
@end
必须配套使用,分别表示开始和结束title
表示接口标题。支持多层级目录,用 /分隔每层目录,不存在的目录会自动创建headers
params
response
,分别表示请求头参数、请求参数、响应参数,支持子参数,只需要缩进一下。markdown
下面的内容会填入到接口文档的 "说明 / 示例" 区域,使用 markdown 语法mock
表示是否自动生成 Mock 接口headers
params
response
markdown
这几个支持多行输入,必须换行,并且缩进。
1
Kilerd 2020-03-14 12:29:34 +08:00
惊了,Tab 缩进
|
2
loading 2020-03-14 12:35:18 +08:00 via Android
jsdoc 我感觉就挺好。
|
3
balabalaguguji OP @Kilerd tab 和空格都支持
|
4
Sapp 2020-03-14 21:29:23 +08:00
你这个能生成 ts 接口文件吗? 我现在公司的可以生成文档同时给前端生成一份 ts 的 api 接口包括 interface,这样前端不用手写定义和接口了,我一直在看有什么开源的能这么搞的
|
5
balabalaguguji OP @Sapp #4 这个是从注释生成文档,跟语言没关系,只要你按照格式注释,就能生成。
|