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

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

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

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

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

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

    76 引用 • 421 回帖
  • RESTful

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

    30 引用 • 114 回帖 • 12 关注

相关帖子

欢迎来到这里!

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

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

    我们这边是写 Javadoc ....

    1 回复
  • 2 1 赞同
    作者

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

    1 回复
  • 我们用嵌入式的注解

    1476771177759

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

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

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

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

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

    1476771297935

    2 回复
  • blague

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

  • 2
    作者

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

  • 88250

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

    1 回复
  • 注解可控方便。

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

  • 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

    每天站会

请输入回帖内容 ...

推荐标签 标签

  • 大数据

    大数据(big data)是指无法在一定时间范围内用常规软件工具进行捕捉、管理和处理的数据集合,是需要新处理模式才能具有更强的决策力、洞察发现力和流程优化能力的海量、高增长率和多样化的信息资产。

    89 引用 • 113 回帖
  • Postman

    Postman 是一款简单好用的 HTTP API 调试工具。

    4 引用 • 3 回帖
  • SMTP

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

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

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

    238 引用 • 224 回帖
  • OpenStack

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

    10 引用 • 9 关注
  • Telegram

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

    5 引用 • 35 回帖 • 1 关注
  • 职场

    找到自己的位置,萌新烦恼少。

    126 引用 • 1699 回帖
  • HHKB

    HHKB 是富士通的 Happy Hacking 系列电容键盘。电容键盘即无接点静电电容式键盘(Capacitive Keyboard)。

    5 引用 • 74 回帖 • 400 关注
  • Webswing

    Webswing 是一个能将任何 Swing 应用通过纯 HTML5 运行在浏览器中的 Web 服务器,详细介绍请看 将 Java Swing 应用变成 Web 应用

    1 引用 • 15 回帖 • 631 关注
  • 禅道

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

    5 引用 • 15 回帖 • 235 关注
  • Vim

    Vim 是类 UNIX 系统文本编辑器 Vi 的加强版本,加入了更多特性来帮助编辑源代码。Vim 的部分增强功能包括文件比较(vimdiff)、语法高亮、全面的帮助系统、本地脚本(Vimscript)和便于选择的可视化模式。

    27 引用 • 66 回帖 • 2 关注
  • uTools

    uTools 是一个极简、插件化、跨平台的现代桌面软件。通过自由选配丰富的插件,打造你得心应手的工具集合。

    5 引用 • 13 回帖
  • Netty

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

    49 引用 • 33 回帖 • 17 关注
  • 域名

    域名(Domain Name),简称域名、网域,是由一串用点分隔的名字组成的 Internet 上某一台计算机或计算机组的名称,用于在数据传输时标识计算机的电子方位(有时也指地理位置)。

    43 引用 • 208 回帖 • 1 关注
  • 架构

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

    139 引用 • 441 回帖
  • HBase

    HBase 是一个分布式的、面向列的开源数据库,该技术来源于 Fay Chang 所撰写的 Google 论文 “Bigtable:一个结构化数据的分布式存储系统”。就像 Bigtable 利用了 Google 文件系统所提供的分布式数据存储一样,HBase 在 Hadoop 之上提供了类似于 Bigtable 的能力。

    17 引用 • 6 回帖 • 31 关注
  • Maven

    Maven 是基于项目对象模型(POM)、通过一小段描述信息来管理项目的构建、报告和文档的软件项目管理工具。

    185 引用 • 318 回帖 • 358 关注
  • 外包

    有空闲时间是接外包好呢还是学习好呢?

    26 引用 • 232 回帖 • 19 关注
  • SendCloud

    SendCloud 由搜狐武汉研发中心孵化的项目,是致力于为开发者提供高质量的触发邮件服务的云端邮件发送平台,为开发者提供便利的 API 接口来调用服务,让邮件准确迅速到达用户收件箱并获得强大的追踪数据。

    2 引用 • 8 回帖 • 426 关注
  • 京东

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

    14 引用 • 102 回帖 • 408 关注
  • Laravel

    Laravel 是一套简洁、优雅的 PHP Web 开发框架。它采用 MVC 设计,是一款崇尚开发效率的全栈框架。

    19 引用 • 22 回帖 • 675 关注
  • Git

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

    204 引用 • 357 回帖
  • 学习

    “梦想从学习开始,事业从实践起步” —— 习近平

    159 引用 • 469 回帖 • 1 关注
  • C++

    C++ 是在 C 语言的基础上开发的一种通用编程语言,应用广泛。C++ 支持多种编程范式,面向对象编程、泛型编程和过程化编程。

    106 引用 • 152 回帖
  • danl
    54 关注
  • IPFS

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

    20 引用 • 245 回帖 • 237 关注
  • 人工智能

    人工智能(Artificial Intelligence)是研究、开发用于模拟、延伸和扩展人的智能的理论、方法、技术及应用系统的一门技术科学。

    64 引用 • 120 回帖