登录 注册

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

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

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

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

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

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

    76 引用 • 421 回帖 • 1 关注
  • RESTful

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

    30 引用 • 114 回帖 • 3 关注
成都 位置
17 回帖
4
3
3
3
2
2
7.9k 42 1.4k 1.2k 1 1.4k 501 5 655 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

近期热议

推荐标签 标签

  • Q&A

    提问之前请先看《提问的智慧》，好的问题比好的答案更有价值。

    6518 引用 • 29299 回帖 • 248 关注
  • Firefox

    Mozilla Firefox 中文俗称“火狐”（正式缩写为 Fx 或 fx，非正式缩写为 FF），是一个开源的网页浏览器，使用 Gecko 排版引擎，支持多种操作系统，如 Windows、OSX 及 Linux 等。

    7 引用 • 30 回帖 • 455 关注
  • 区块链

    区块链是分布式数据存储、点对点传输、共识机制、加密算法等计算机技术的新型应用模式。所谓共识机制是区块链系统中实现不同节点之间建立信任、获取权益的数学算法 。

    91 引用 • 751 回帖
  • JWT

    JWT（JSON Web Token）是一种用于双方之间传递信息的简洁的、安全的表述性声明规范。JWT 作为一个开放的标准（RFC 7519），定义了一种简洁的，自包含的方法用于通信双方之间以 JSON 的形式安全的传递信息。

    20 引用 • 15 回帖 • 17 关注
  • 创业

    你比 99% 的人都优秀么？

    82 引用 • 1398 回帖 • 2 关注
  • 996

    “工作 996， 生病 ICU”

    13 引用 • 200 回帖 • 1 关注
  • PWA

    PWA（Progressive Web App）是 Google 在 2015 年提出、2016 年 6 月开始推广的项目。它结合了一系列现代 Web 技术，在网页应用中实现和原生应用相近的用户体验。

    14 引用 • 69 回帖 • 132 关注
  • danl
    • 61 关注
  • 小说

    小说是以刻画人物形象为中心，通过完整的故事情节和环境描写来反映社会生活的文学体裁。

    28 引用 • 108 回帖 • 1 关注
  • iOS

    iOS 是由苹果公司开发的移动操作系统，最早于 2007 年 1 月 9 日的 Macworld 大会上公布这个系统，最初是设计给 iPhone 使用的，后来陆续套用到 iPod touch、iPad 以及 Apple TV 等产品上。iOS 与苹果的 Mac OS X 操作系统一样，属于类 Unix 的商业操作系统。

    84 引用 • 139 回帖 • 1 关注
  • BAE

    百度应用引擎（Baidu App Engine）提供了 PHP、Java、Python 的执行环境，以及云存储、消息服务、云数据库等全面的云服务。它可以让开发者实现自动地部署和管理应用，并且提供动态扩容和负载均衡的运行环境，让开发者不用考虑高成本的运维工作，只需专注于业务逻辑，大大降低了开发者学习和迁移的成本。

    19 引用 • 75 回帖 • 621 关注
  • ReactiveX

    ReactiveX 是一个专注于异步编程与控制可观察数据（或者事件）流的 API。它组合了观察者模式，迭代器模式和函数式编程的优秀思想。

    1 引用 • 2 回帖 • 126 关注
  • Android

    Android 是一种以 Linux 为基础的开放源码操作系统，主要使用于便携设备。2005 年由 Google 收购注资，并拉拢多家制造商组成开放手机联盟开发改良，逐渐扩展到到平板电脑及其他领域上。

    333 引用 • 323 回帖 • 70 关注
  • 友情链接

    确认过眼神后的灵魂连接，站在链在！

    24 引用 • 373 回帖 • 4 关注
  • Hadoop

    Hadoop 是由 Apache 基金会所开发的一个分布式系统基础架构。用户可以在不了解分布式底层细节的情况下，开发分布式程序。充分利用集群的威力进行高速运算和存储。

    82 引用 • 122 回帖 • 614 关注
  • IPFS

    IPFS（InterPlanetary File System，星际文件系统）是永久的、去中心化保存和共享文件的方法，这是一种内容可寻址、版本化、点对点超媒体的分布式协议。请浏览 IPFS 入门笔记了解更多细节。

    20 引用 • 245 回帖 • 228 关注
  • 坑

    一些有用的避坑指南。

    69 引用 • 93 回帖
  • OAuth

    OAuth 协议为用户资源的授权提供了一个安全的、开放而又简易的标准。与以往的授权方式不同之处是 oAuth 的授权不会使第三方触及到用户的帐号信息（如用户名与密码），即第三方无需使用用户的用户名与密码就可以申请获得该用户资源的授权，因此 oAuth 是安全的。oAuth 是 Open Authorization 的简写。

    36 引用 • 103 回帖 • 8 关注
  • WordPress

    WordPress 是一个使用 PHP 语言开发的博客平台，用户可以在支持 PHP 和 MySQL 数据库的服务器上架设自己的博客。也可以把 WordPress 当作一个内容管理系统（CMS）来使用。WordPress 是一个免费的开源项目，在 GNU 通用公共许可证（GPLv2）下授权发布。

    45 引用 • 113 回帖 • 317 关注
  • InfluxDB

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

    2 引用 • 53 关注
  • FreeMarker

    FreeMarker 是一款好用且功能强大的 Java 模版引擎。

    23 引用 • 20 回帖 • 427 关注
  • C

    C 语言是一门通用计算机编程语言，应用广泛。C 语言的设计目标是提供一种能以简易的方式编译、处理低级存储器、产生少量的机器码以及不需要任何运行环境支持便能运行的编程语言。

    83 引用 • 165 回帖 • 47 关注
  • 微软

    微软是一家美国跨国科技公司，也是世界 PC 软件开发的先导，由比尔·盖茨与保罗·艾伦创办于 1975 年，公司总部设立在华盛顿州的雷德蒙德（Redmond，邻近西雅图）。以研发、制造、授权和提供广泛的电脑软件服务业务为主。

    8 引用 • 44 回帖
  • 七牛云

    七牛云是国内领先的企业级公有云服务商，致力于打造以数据为核心的场景化 PaaS 服务。围绕富媒体场景，七牛先后推出了对象存储，融合 CDN 加速，数据通用处理，内容反垃圾服务，以及直播云服务等。

    25 引用 • 215 回帖 • 163 关注
  • FFmpeg

    FFmpeg 是一套可以用来记录、转换数字音频、视频，并能将其转化为流的开源计算机程序。

    22 引用 • 31 回帖 • 3 关注
  • Node.js

    Node.js 是一个基于 Chrome JavaScript 运行时建立的平台， 用于方便地搭建响应速度快、易于扩展的网络应用。Node.js 使用事件驱动， 非阻塞 I/O 模型而得以轻量和高效。

    138 引用 • 268 回帖 • 199 关注
  • Caddy

    Caddy 是一款默认自动启用 HTTPS 的 HTTP/2 Web 服务器。

    10 引用 • 54 回帖 • 131 关注

最新标签