V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
V2EX 提问指南
balabalaguguji
V2EX  ›  问与答

从注释生成文档,欢迎各位大佬喷

  •  
  •   balabalaguguji · 2020-03-14 11:59:15 +08:00 · 981 次点击
    这是一个创建于 1711 天前的主题,其中的信息可能已经有所发展或是发生改变。

    很多其他产品有过注释生成文档的做法了,但是感觉格式稍微有些复杂,编写不够方便,代码污染

    注释格式经过了很长时间的思考,怎样才能更优雅方便?

    最终格式如下图,如有不爽的地方,请各位使劲喷: QQ 截图 20200314114649.png

    • 支持所有语言,只要按照上面的规则去添加注释,就可以自动扫描创建成一个易文档的接口文档。
    • 缩进必须是对齐的
    • @easydoc api @end 必须配套使用,分别表示开始和结束
    • title 表示接口标题。支持多层级目录,用 /分隔每层目录,不存在的目录会自动创建
    • 参数块当前只支持 3 个,headers params response,分别表示请求头参数、请求参数、响应参数,支持子参数,只需要缩进一下。
    • markdown 下面的内容会填入到接口文档的 "说明 / 示例" 区域,使用 markdown 语法
    • mock 表示是否自动生成 Mock 接口
    • headers params response markdown 这几个支持多行输入,必须换行,并且缩进。
    • method+url 判断文档是否已存在,存在的更新,不存在则新建

    最终效果图如下,或 在线浏览 完整文档

    ss.png 233.png

    5 条回复    2020-03-14 22:53:25 +08:00
    Kilerd
        1
    Kilerd  
       2020-03-14 12:29:34 +08:00
    惊了,Tab 缩进
    loading
        2
    loading  
       2020-03-14 12:35:18 +08:00 via Android
    jsdoc 我感觉就挺好。
    balabalaguguji
        3
    balabalaguguji  
    OP
       2020-03-14 12:37:13 +08:00
    @Kilerd tab 和空格都支持
    Sapp
        4
    Sapp  
       2020-03-14 21:29:23 +08:00
    你这个能生成 ts 接口文件吗? 我现在公司的可以生成文档同时给前端生成一份 ts 的 api 接口包括 interface,这样前端不用手写定义和接口了,我一直在看有什么开源的能这么搞的
    balabalaguguji
        5
    balabalaguguji  
    OP
       2020-03-14 22:53:25 +08:00
    @Sapp #4 这个是从注释生成文档,跟语言没关系,只要你按照格式注释,就能生成。
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   实用小工具   ·   1879 人在线   最高记录 6679   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 24ms · UTC 16:33 · PVG 00:33 · LAX 08:33 · JFK 11:33
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.