V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
jry
V2EX  ›  API

关于 API 文档撰写方式

  •  
  •   jry · 2021-04-23 10:22:49 +08:00 · 2019 次点击
    这是一个创建于 1061 天前的主题,其中的信息可能已经有所发展或是发生改变。

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

    7 条回复    2021-04-24 14:51:33 +08:00
    mopland
        1
    mopland  
       2021-04-23 14:10:35 +08:00
    我们是定制一套规范,都按规范来书写,同时框架自动解析生成文档,接口校验、权限验证都使用同一套方案。

    http://notes.veryide.com/gateway.md
    dzdh
        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
    Rwing
        3
    Rwing  
       2021-04-23 14:17:22 +08:00   ❤️ 3
    相信我,如果是在另外的工具里写,那么 90%的程序员都不会及时更新的,导致文档滞后或错误。
    所以最佳做法一定是在代码里写
    lplk
        4
    lplk  
       2021-04-23 14:18:10 +08:00 via Android
    我目前用 openapi ,我觉得这个挺好
    jjwjiang
        5
    jjwjiang  
       2021-04-23 16:02:09 +08:00
    swagger 不是自带通过注解生成 openapi 文档的功能吗
    jry
        6
    jry  
    OP
       2021-04-24 14:50:39 +08:00
    那就 openapi 吧
    @Rwing 我觉得你这点说的很有道理
    jry
        7
    jry  
    OP
       2021-04-24 14:51:33 +08:00
    @jjwjiang 就是觉得注解设计的有点繁琐,不够简洁?
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   我们的愿景   ·   实用小工具   ·   5379 人在线   最高记录 6543   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 32ms · UTC 06:55 · PVG 14:55 · LAX 23:55 · JFK 02:55
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.