登录 注册

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

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

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

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

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

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

    77 引用 • 430 回帖 • 2 关注
  • RESTful

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

    30 引用 • 114 回帖 • 2 关注
成都 位置
17 回帖
4
3
3
3
2
2
8.1k 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

近期热议

推荐标签 标签

  • React

    React 是 Facebook 开源的一个用于构建 UI 的 JavaScript 库。

    192 引用 • 291 回帖 • 384 关注
  • 深度学习

    深度学习（Deep Learning）是机器学习的分支，是一种试图使用包含复杂结构或由多重非线性变换构成的多个处理层对数据进行高层抽象的算法。

    53 引用 • 40 回帖
  • 链滴

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

    记录生活，连接点滴

    153 引用 • 3783 回帖 • 1 关注
  • Python

    Python 是一种面向对象、直译式电脑编程语言，具有近二十年的发展历史，成熟且稳定。它包含了一组完善而且容易理解的标准库，能够轻松完成很多常见的任务。它的语法简捷和清晰，尽量使用无异义的英语单词，与其它大多数程序设计语言使用大括号不一样，它使用缩进来定义语句块。

    543 引用 • 672 回帖 • 1 关注
  • Rust

    Rust 是一门赋予每个人构建可靠且高效软件能力的语言。Rust 由 Mozilla 开发，最早发布于 2014 年 9 月。

    58 引用 • 22 回帖
  • DevOps

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

    47 引用 • 25 回帖
  • Flume

    Flume 是一套分布式的、可靠的，可用于有效地收集、聚合和搬运大量日志数据的服务架构。

    9 引用 • 6 回帖 • 629 关注
  • Linux

    Linux 是一套免费使用和自由传播的类 Unix 操作系统，是一个基于 POSIX 和 Unix 的多用户、多任务、支持多线程和多 CPU 的操作系统。它能运行主要的 Unix 工具软件、应用程序和网络协议，并支持 32 位和 64 位硬件。Linux 继承了 Unix 以网络为核心的设计思想，是一个性能稳定的多用户网络操作系统。

    943 引用 • 943 回帖
  • DNSPod

    DNSPod 建立于 2006 年 3 月份，是一款免费智能 DNS 产品。 DNSPod 可以为同时有电信、网通、教育网服务器的网站提供智能的解析，让电信用户访问电信的服务器，网通的用户访问网通的服务器，教育网的用户访问教育网的服务器，达到互联互通的效果。

    6 引用 • 26 回帖 • 510 关注
  • 互联网

    互联网（Internet），又称网际网络，或音译因特网、英特网。互联网始于 1969 年美国的阿帕网，是网络与网络之间所串连成的庞大网络，这些网络以一组通用的协议相连，形成逻辑上的单一巨大国际网络。

    98 引用 • 344 回帖
  • Kafka

    Kafka 是一种高吞吐量的分布式发布订阅消息系统，它可以处理消费者规模的网站中的所有动作流数据。 这种动作（网页浏览，搜索和其他用户的行动）是现代系统中许多功能的基础。 这些数据通常是由于吞吐量的要求而通过处理日志和日志聚合来解决。

    36 引用 • 35 回帖
  • InfluxDB

    InfluxDB 是一个开源的没有外部依赖的时间序列数据库。适用于记录度量，事件及实时分析。

    2 引用 • 71 关注
  • GitBook

    GitBook 使您的团队可以轻松编写和维护高质量的文档。 分享知识，提高团队的工作效率，让用户满意。

    3 引用 • 8 回帖 • 4 关注
  • IDEA

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

    180 引用 • 400 回帖
  • Elasticsearch

    Elasticsearch 是一个基于 Lucene 的搜索服务器。它提供了一个分布式多用户能力的全文搜索引擎，基于 RESTful 接口。Elasticsearch 是用 Java 开发的，并作为 Apache 许可条款下的开放源码发布，是当前流行的企业级搜索引擎。设计用于云计算中，能够达到实时搜索，稳定，可靠，快速，安装使用方便。

    117 引用 • 99 回帖 • 211 关注
  • 尊园地产

    昆明尊园房地产经纪有限公司，即：Kunming Zunyuan Property Agency Company Limited（简称“尊园地产”）于 2007 年 6 月开始筹备，2007 年 8 月 18 日正式成立，注册资本 200 万元，公司性质为股份经纪有限公司，主营业务为：代租、代售、代办产权过户、办理银行按揭、担保、抵押、评估等。

    1 引用 • 22 回帖 • 762 关注
  • 数据库

    据说 99% 的性能瓶颈都在数据库。

    340 引用 • 708 回帖
  • 博客

    记录并分享人生的经历。

    273 引用 • 2388 回帖
  • SVN

    SVN 是 Subversion 的简称，是一个开放源代码的版本控制系统，相较于 RCS、CVS，它采用了分支管理系统，它的设计目标就是取代 CVS。

    29 引用 • 98 回帖 • 680 关注
  • AngularJS

    AngularJS 诞生于 2009 年，由 Misko Hevery 等人创建，后为 Google 所收购。是一款优秀的前端 JS 框架，已经被用于 Google 的多款产品当中。AngularJS 有着诸多特性，最为核心的是：MVC、模块化、自动化双向数据绑定、语义化标签、依赖注入等。2.0 版本后已经改名为 Angular。

    12 引用 • 50 回帖 • 474 关注
  • 音乐

    你听到信仰的声音了么？

    60 引用 • 511 回帖
  • 前端

    前端技术一般分为前端设计和前端开发，前端设计可以理解为网站的视觉设计，前端开发则是网站的前台代码实现，包括 HTML、CSS 以及 JavaScript 等。

    247 引用 • 1348 回帖
  • Tomcat

    Tomcat 最早是由 Sun Microsystems 开发的一个 Servlet 容器，在 1999 年被捐献给 ASF（Apache Software Foundation），隶属于 Jakarta 项目，现在已经独立为一个顶级项目。Tomcat 主要实现了 JavaEE 中的 Servlet、JSP 规范，同时也提供 HTTP 服务，是市场上非常流行的 Java Web 容器。

    162 引用 • 529 回帖
  • ZooKeeper

    ZooKeeper 是一个分布式的，开放源码的分布式应用程序协调服务，是 Google 的 Chubby 一个开源的实现，是 Hadoop 和 HBase 的重要组件。它是一个为分布式应用提供一致性服务的软件，提供的功能包括：配置维护、域名服务、分布式同步、组服务等。

    59 引用 • 29 回帖 • 5 关注
  • Ant-Design

    Ant Design 是服务于企业级产品的设计体系，基于确定和自然的设计价值观上的模块化解决方案，让设计者和开发者专注于更好的用户体验。

    17 引用 • 23 回帖
  • 强迫症

    强迫症（OCD）属于焦虑障碍的一种类型，是一组以强迫思维和强迫行为为主要临床表现的神经精神疾病，其特点为有意识的强迫和反强迫并存，一些毫无意义、甚至违背自己意愿的想法或冲动反反复复侵入患者的日常生活。

    15 引用 • 161 回帖
  • 链书

    链书（Chainbook）是 B3log 开源社区提供的区块链纸质书交易平台，通过 B3T 实现共享激励与价值链。可将你的闲置书籍上架到链书，我们共同构建这个全新的交易平台，让闲置书籍继续发挥它的价值。

    链书社

    链书目前已经下线，也许以后还有计划重制上线。

    14 引用 • 257 回帖

最新标签