登录 注册

大家用什么工具生成 restFul 的 API 文档？

本贴最后更新于 2987 天前，其中的信息可能已经时移世易

之前用过 swagger 和 http://apidocjs.com/
但感觉侵入性都比较强， apidocjs 侵入性稍微低一点（只用注释）

大家用什么工具生成 restFul 的 API 文档？

  • 文档
    56 引用 • 1289 回帖 • 2 关注
  • API

    应用程序编程接口（Application Programming Interface）是一些预先定义的函数，目的是提供应用程序与开发人员基于某软件或硬件得以访问一组例程的能力，而又无需访问源码，或理解内部工作机制的细节。

    77 引用 • 430 回帖
  • RESTful

    一种软件架构设计风格而不是标准，提供了一组设计原则和约束条件，主要用于客户端和服务器交互类的软件。基于这个风格设计的软件可以更简洁，更有层次，更易于实现缓存等机制。

    30 引用 • 114 回帖 • 3 关注
成都 位置
17 回帖
4
3
3
3
2
2
8.2k 42 1.4k 1.3k 1 1.4k 501 5 665 2.8k

相关帖子

17 回帖
大家用什么工具生成 restFul 的 API 文档？

欢迎来到这里！

我们正在构建一个小众社区，大家在这里相互信任，以平等 • 自由 • 奔放的价值观进行分享交流。最终，希望大家能够找到与自己志同道合的伙伴，共同成长。

注册 关于
请输入回帖内容 ...
  • 88250 •
    订阅者

    我们这边是写 Javadoc ....

    1 回复
  • 2 • • 1 赞同
    作者

    javadoc 感觉很不友好呢， 特别是对于 iOS APP 的开发来说， 他们根本不爱看 javadoc

    1 回复
  • DASHU •
    订阅者 支持者 勇士

    我们用嵌入式的注解

    1476771177759

    在方法的上面写方法的说明。

    同时出参和入参，都是一个实体。

    同样实体里面也用注解写好。

    需要的时候，用程序把注解读出来，生成出文档。

    再上一张实体里面的注解：

    1476771297935

    2 回复
  • blague •

    反而觉得用 javadoc 比较好。
    自定义 doclet 多好
    为什么要用注解。

  • 2 •
    作者

    这个和 swagger 差不多， 侵入式感觉很强

  • 88250 •
    订阅者

    Javadoc 生成的也是 HTML 啊，只要写的时候稍微排版一下就萌萌了啦

    1 回复
  • DASHU •
    订阅者 支持者 勇士

    注解可控方便。

    比较容易按自己想要的姿势生成文档。

  • blague •

    我同意 D 的观点，其实都一样，只是看你怎么去生成文档。
    但我觉得注解还是对代码的侵入太强了。
    而 javadoc 会更好一点。

    1 回复
  • 88250 •
    订阅者

    握个爪子 😙

  • yangyujiao •

    这东西不是开发前就写好的吗？？？ 之前公司在接口设计的时候连 request 跟 response 都是写好的，貌似他们是用 junit 测试出的 response。
    应该给你们看看那种文档，纯手写的。。。 但是巨清晰，我看过那个 swagger 写的，看起来根本不方便。。。
    我电脑目前没有那个文档，可能在硬盘里 等我回去找找看。

    1 回复
  • 2 •
    作者

    下面是两个例子， 我觉得超清晰啊。 而且手动写文档真的很费时间
    http://apidocjs.com/example/
    http://petstore.swagger.io/
    http://editor.swagger.io/

    1 回复
  • yangyujiao •

    那是你看着人家例子挺清晰的，自己写出来可不一定。而且 不觉得这样找起来很烦吗。一个 excel 全部搞定了，而且清晰易懂，好 copy。
    之前这边在 wiki 里用 markdown 写的接口，我看了都得崩溃了，修改一下也特别麻烦。
    我之前看了这边领导给我发的 swagger 管理的，还是觉得不是很方便，但是他说好处是可以同步，一个人修改了，大家都可以看到。但是其实我觉得，你要不通知一下修改了接口，别人会去关注吗？？？
    我们之前一个 excel 里各种模块巨清楚，看来我必须回去找下文档，让你们看看啦。

    最后，选用什么方式，首先是自己觉得便利就好。另外我觉得要省时省力最好。

    1 回复
  • zonghua •

    那样的公司太好了啊，工作的时候只要对着文档干活，明确了啊

    1 回复
  • yangyujiao •

    附赠一个以前公司的接口文档
    ea60b2e8f6ee467db773c5fb4babbd3d.png

    1 回复
  • zonghua •

    这样的话写代码真的是只占 10% 的工作量

    1 回复
  • yangyujiao •

    我现在的公司就是 80% 的时间是浪费在跟产品还有后台的沟通上面·····

    1 回复
  • zonghua •

    每天站会

请输入回帖内容 ...
2
成都
回帖
31
 帖子
6
 积分
1411

近期热议

推荐标签 标签

  • 工具

    子曰：“工欲善其事，必先利其器。”

    288 引用 • 734 回帖 • 1 关注
  • 游戏

    沉迷游戏伤身，强撸灰飞烟灭。

    177 引用 • 816 回帖
  • Facebook

    Facebook 是一个联系朋友的社交工具。大家可以通过它和朋友、同事、同学以及周围的人保持互动交流，分享无限上传的图片，发布链接和视频，更可以增进对朋友的了解。

    4 引用 • 15 回帖 • 440 关注
  • Dubbo

    Dubbo 是一个分布式服务框架，致力于提供高性能和透明化的 RPC 远程服务调用方案，是 [阿里巴巴] SOA 服务化治理方案的核心框架，每天为 2,000+ 个服务提供 3,000,000,000+ 次访问量支持，并被广泛应用于阿里巴巴集团的各成员站点。

    60 引用 • 82 回帖 • 604 关注
  • Windows

    Microsoft Windows 是美国微软公司研发的一套操作系统，它问世于 1985 年，起初仅仅是 Microsoft-DOS 模拟环境，后续的系统版本由于微软不断的更新升级，不但易用，也慢慢的成为家家户户人们最喜爱的操作系统。

    223 引用 • 474 回帖
  • 服务器

    服务器，也称伺服器，是提供计算服务的设备。由于服务器需要响应服务请求，并进行处理，因此一般来说服务器应具备承担服务并且保障服务的能力。

    125 引用 • 588 回帖
  • Solo

    Solo 是一款小而美的开源博客系统，专为程序员设计。Solo 有着非常活跃的社区，可将文章作为帖子推送到社区，来自社区的回帖将作为博客评论进行联动（具体细节请浏览 B3log 构思 - 分布式社区网络）。

    这是一种全新的网络社区体验，让热爱记录和分享的你不再感到孤单！

    1435 引用 • 10056 回帖 • 489 关注
  • 链滴

    链滴是一个记录生活的地方。

    记录生活，连接点滴

    156 引用 • 3792 回帖 • 1 关注
  • 锤子科技

    锤子科技（Smartisan）成立于 2012 年 5 月，是一家制造移动互联网终端设备的公司，公司的使命是用完美主义的工匠精神，打造用户体验一流的数码消费类产品（智能手机为主），改善人们的生活质量。

    4 引用 • 31 回帖
  • Electron

    Electron 基于 Chromium 和 Node.js，让你可以使用 HTML、CSS 和 JavaScript 构建应用。它是一个由 GitHub 及众多贡献者组成的活跃社区共同维护的开源项目，兼容 Mac、Windows 和 Linux，它构建的应用可在这三个操作系统上面运行。

    15 引用 • 136 回帖 • 1 关注
  • Angular

    Angular 是 AngularJS 的新版本。

    26 引用 • 66 回帖 • 536 关注
  • BookxNote

    BookxNote 是一款全新的电子书学习工具，助力您的学习与思考，让您的大脑更高效的记忆。

    笔记整理交给我，一心只读圣贤书。

    1 引用 • 1 回帖 • 1 关注
  • IDEA

    IDEA 全称 IntelliJ IDEA，是一款 Java 语言开发的集成环境，在业界被公认为最好的 Java 开发工具之一。IDEA 是 JetBrains 公司的产品，这家公司总部位于捷克共和国的首都布拉格，开发人员以严谨著称的东欧程序员为主。

    181 引用 • 400 回帖
  • wolai

    我来 wolai：不仅仅是未来的云端笔记！

    2 引用 • 14 回帖 • 1 关注
  • IBM

    IBM（国际商业机器公司）或万国商业机器公司，简称 IBM（International Business Machines Corporation），总公司在纽约州阿蒙克市。1911 年托马斯·沃森创立于美国，是全球最大的信息技术和业务解决方案公司，拥有全球雇员 30 多万人，业务遍及 160 多个国家和地区。

    17 引用 • 53 回帖 • 139 关注
  • 旅游

    希望你我能在旅途中找到人生的下一站。

    93 引用 • 899 回帖 • 1 关注
  • HTML

    HTML5 是 HTML 下一个的主要修订版本，现在仍处于发展阶段。广义论及 HTML5 时，实际指的是包括 HTML、CSS 和 JavaScript 在内的一套技术组合。

    107 引用 • 295 回帖
  • OpenStack

    OpenStack 是一个云操作系统，通过数据中心可控制大型的计算、存储、网络等资源池。所有的管理通过前端界面管理员就可以完成，同样也可以通过 Web 接口让最终用户部署资源。

    10 引用 • 1 关注
  • 书籍

    宋真宗赵恒曾经说过：“书中自有黄金屋，书中自有颜如玉。”

    78 引用 • 391 回帖
  • Gitea

    Gitea 是一个开源社区驱动的轻量级代码托管解决方案，后端采用 Go 编写，采用 MIT 许可证。

    4 引用 • 16 回帖
  • 脑图

    脑图又叫思维导图，是表达发散性思维的有效图形思维工具 ，它简单却又很有效，是一种实用性的思维工具。

    30 引用 • 96 回帖 • 1 关注
  • 京东

    京东是中国最大的自营式电商企业，2015 年第一季度在中国自营式 B2C 电商市场的占有率为 56.3%。2014 年 5 月，京东在美国纳斯达克证券交易所正式挂牌上市（股票代码：JD），是中国第一个成功赴美上市的大型综合型电商平台，与腾讯、百度等中国互联网巨头共同跻身全球前十大互联网公司排行榜。

    14 引用 • 102 回帖 • 354 关注
  • Bootstrap

    Bootstrap 是 Twitter 推出的一个用于前端开发的开源工具包。它由 Twitter 的设计师 Mark Otto 和 Jacob Thornton 合作开发，是一个 CSS / HTML 框架。

    18 引用 • 33 回帖 • 667 关注
  • DevOps

    DevOps（Development 和 Operations 的组合词）是一组过程、方法与系统的统称，用于促进开发（应用程序/软件工程）、技术运营和质量保障（QA）部门之间的沟通、协作与整合。

    51 引用 • 25 回帖
  • QQ

    1999 年 2 月腾讯正式推出“腾讯 QQ”，在线用户由 1999 年的 2 人（马化腾和张志东）到现在已经发展到上亿用户了，在线人数超过一亿，是目前使用最广泛的聊天软件之一。

    45 引用 • 557 回帖 • 44 关注
  • 博客

    记录并分享人生的经历。

    273 引用 • 2388 回帖
  • PHP

    PHP（Hypertext Preprocessor）是一种开源脚本语言。语法吸收了 C 语言、 Java 和 Perl 的特点，主要适用于 Web 开发领域，据说是世界上最好的编程语言。

    179 引用 • 407 回帖 • 491 关注

最新标签