登录 注册

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

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

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

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

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

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

    76 引用 • 421 回帖
  • RESTful

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

    30 引用 • 114 回帖 • 1 关注
成都 位置
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

近期热议

推荐标签 标签

  • 新人

    让我们欢迎这对新人。哦，不好意思说错了，让我们欢迎这位新人！
    新手上路，请谨慎驾驶！

    51 引用 • 226 回帖
  • 分享

    有什么新发现就分享给大家吧！

    242 引用 • 1747 回帖 • 1 关注
  • Firefox

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

    7 引用 • 30 回帖 • 452 关注
  • Gzip

    gzip （GNU zip）是 GNU 自由软件的文件压缩程序。我们在 Linux 中经常会用到后缀为 .gz 的文件，它们就是 Gzip 格式的。现今已经成为互联网上使用非常普遍的一种数据压缩格式，或者说一种文件格式。

    9 引用 • 12 回帖 • 111 关注
  • JSON

    JSON （JavaScript Object Notation）是一种轻量级的数据交换格式。易于人类阅读和编写。同时也易于机器解析和生成。

    51 引用 • 190 回帖 • 1 关注
  • SQLServer

    SQL Server 是由 [微软] 开发和推广的关系数据库管理系统（DBMS），它最初是由 微软、Sybase 和 Ashton-Tate 三家公司共同开发的，并于 1988 年推出了第一个 OS/2 版本。

    19 引用 • 31 回帖 • 4 关注
  • Swift

    Swift 是苹果于 2014 年 WWDC（苹果开发者大会）发布的开发语言，可与 Objective-C 共同运行于 Mac OS 和 iOS 平台，用于搭建基于苹果平台的应用程序。

    34 引用 • 37 回帖 • 497 关注
  • NGINX

    NGINX 是一个高性能的 HTTP 和反向代理服务器，也是一个 IMAP/POP3/SMTP 代理服务器。 NGINX 是由 Igor Sysoev 为俄罗斯访问量第二的 Rambler.ru 站点开发的，第一个公开版本 0.1.0 发布于 2004 年 10 月 4 日。

    311 引用 • 546 回帖 • 34 关注
  • Netty

    Netty 是一个基于 NIO 的客户端-服务器编程框架，使用 Netty 可以让你快速、简单地开发出一个可维护、高性能的网络应用，例如实现了某种协议的客户、服务端应用。

    49 引用 • 33 回帖 • 22 关注
  • Telegram

    Telegram 是一个非盈利性、基于云端的即时消息服务。它提供了支持各大操作系统平台的开源的客户端，也提供了很多强大的 APIs 给开发者创建自己的客户端和机器人。

    5 引用 • 35 回帖
  • Rust

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

    57 引用 • 22 回帖 • 4 关注
  • 快应用

    快应用 是基于手机硬件平台的新型应用形态；标准是由主流手机厂商组成的快应用联盟联合制定；快应用标准的诞生将在研发接口、能力接入、开发者服务等层面建设标准平台；以平台化的生态模式对个人开发者和企业开发者全品类开放。

    15 引用 • 127 回帖 • 2 关注
  • Git

    Git 是 Linux Torvalds 为了帮助管理 Linux 内核开发而开发的一个开放源码的版本控制软件。

    205 引用 • 357 回帖
  • 正则表达式

    正则表达式（Regular Expression）使用单个字符串来描述、匹配一系列遵循某个句法规则的字符串。

    31 引用 • 94 回帖
  • gRpc
    10 引用 • 8 回帖 • 54 关注
  • V2EX

    V2EX 是创意工作者们的社区。这里目前汇聚了超过 400,000 名主要来自互联网行业、游戏行业和媒体行业的创意工作者。V2EX 希望能够成为创意工作者们的生活和事业的一部分。

    17 引用 • 236 回帖 • 418 关注
  • 禅道

    禅道是一款国产的开源项目管理软件，她的核心管理思想基于敏捷方法 scrum，内置了产品管理和项目管理，同时又根据国内研发现状补充了测试管理、计划管理、发布管理、文档管理、事务管理等功能，在一个软件中就可以将软件研发中的需求、任务、bug、用例、计划、发布等要素有序的跟踪管理起来，完整地覆盖了项目管理的核心流程。

    5 引用 • 15 回帖 • 222 关注
  • Kubernetes

    Kubernetes 是 Google 开源的一个容器编排引擎，它支持自动化部署、大规模可伸缩、应用容器化管理。

    108 引用 • 54 回帖 • 1 关注
  • 服务

    提供一个服务绝不仅仅是简单的把硬件和软件累加在一起，它包括了服务的可靠性、服务的标准化、以及对服务的监控、维护、技术支持等。

    41 引用 • 24 回帖 • 3 关注
  • 架构

    我们平时所说的“架构”主要是指软件架构，这是有关软件整体结构与组件的抽象描述，用于指导软件系统各个方面的设计。另外还有“业务架构”、“网络架构”、“硬件架构”等细分领域。

    140 引用 • 441 回帖
  • JWT

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

    20 引用 • 15 回帖 • 16 关注
  • SMTP

    SMTP（Simple Mail Transfer Protocol）即简单邮件传输协议，它是一组用于由源地址到目的地址传送邮件的规则，由它来控制信件的中转方式。SMTP 协议属于 TCP/IP 协议簇，它帮助每台计算机在发送或中转信件时找到下一个目的地。

    4 引用 • 18 回帖 • 587 关注
  • CentOS

    CentOS（Community Enterprise Operating System）是 Linux 发行版之一，它是来自于 Red Hat Enterprise Linux 依照开放源代码规定释出的源代码所编译而成。由于出自同样的源代码，因此有些要求高度稳定的服务器以 CentOS 替代商业版的 Red Hat Enterprise Linux 使用。两者的不同在于 CentOS 并不包含封闭源代码软件。

    238 引用 • 224 回帖
  • RIP

    愿逝者安息！

    8 引用 • 92 回帖 • 290 关注
  • MongoDB

    MongoDB（来自于英文单词“Humongous”，中文含义为“庞大”）是一个基于分布式文件存储的数据库，由 C++ 语言编写。旨在为应用提供可扩展的高性能数据存储解决方案。MongoDB 是一个介于关系数据库和非关系数据库之间的产品，是非关系数据库当中功能最丰富，最像关系数据库的。它支持的数据结构非常松散，是类似 JSON 的 BSON 格式，因此可以存储比较复杂的数据类型。

    90 引用 • 59 回帖 • 2 关注
  • Spring

    Spring 是一个开源框架，是于 2003 年兴起的一个轻量级的 Java 开发框架，由 Rod Johnson 在其著作《Expert One-On-One J2EE Development and Design》中阐述的部分理念和原型衍生而来。它是为了解决企业应用开发的复杂性而创建的。框架的主要优势之一就是其分层架构，分层架构允许使用者选择使用哪一个组件，同时为 JavaEE 应用程序开发提供集成的框架。

    941 引用 • 1458 回帖 • 153 关注
  • Tomcat

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

    162 引用 • 529 回帖 • 2 关注

最新标签