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

API 文档是和代码在一起比较好还是分开比较好?

  •  1
     
  •   wuchengkai0 · 150 天前 · 1196 次点击
    这是一个创建于 150 天前的主题,其中的信息可能已经有所发展或是发生改变。

    写一起:

    优点: 好维护

    缺点: 注解太多?

    不写一起:

    缺点: 不利于维护

    理论上应该是文档先行,后写代码。大家都是如何做的?

    10 回复  |  直到 2018-11-19 17:04:53 +08:00
        1
    noNOno   150 天前   ♥ 1
    我个人,文档 /代码是写在一起.有项目规范,就遵从规范.
    先写文档 /注解,留个空类 /空方法,然后再去实现.
        2
    CFO   150 天前 via Android
    不好维护的文档有什么用?过期的 不能用的文档还不如没有 浪费大家调接口的时间
        3
    luozic   150 天前 via iPhone
    swagger codegen 系列
        4
    suzic   150 天前 via Android
    用 apidoc 写在注释里。重点是写接口的一定要理解产品需求,不然写出来前端也没法用
        5
    TommyLemon   150 天前
    分开好。
    要写代码(注解、注释等)不只是增加开发工作量,还得重新部署才生效,后续维护也麻烦。
        6
    TommyLemon   150 天前
        7
    TommyLemon   150 天前
    一键自动接口回归测试,不需要写任何代码(注解、注释等全都不要)
        9
    TommyLemon   150 天前
        10
    TommyLemon   150 天前
    自动保存请求记录、自动生成接口文档

    还有
    自动生成封装请求 JSON 的 Android 与 iOS 代码
    一键下载自动生成的 JavaBean
    多个测试账号、一键共享测试用例


    附 开放源码、视频教程
    GitHub 右上角点 ⭐Star 支持下吧 ^_^
    https://github.com/TommyLemon/APIJSONAuto
    关于   ·   FAQ   ·   API   ·   我们的愿景   ·   广告投放   ·   感谢   ·   实用小工具   ·   3018 人在线   最高记录 4385   ·  
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.3 · 20ms · UTC 10:54 · PVG 18:54 · LAX 03:54 · JFK 06:54
    ♥ Do have faith in what you're doing.
    沪ICP备16043287号-1