很高兴能回答你的问题，对于每个开发人员来说，都有自己喜欢的API接口文档，在这里我给大家推荐三款我比较喜欢的在线API文档。

apizza

apizza 是一个极客专属的api协作管理工具,你可以在这里进行api测试,方便快捷的编写api文档,智能识别参数,自动生成代码,流程测试,让你的团队协作更高效。

网址：https://www.apizza.net/

个人用都是免费版，可以创建8个项目，写200个接口，可以同时绑定两个开发者，基本上能满足绝大多数的项目需求，我有个直播的项目，一共写了将近180个接口，如果实在不够就按两个项目去写也是可以的。

当一个项目完成之后，支持导出json格式，在其他工具当中是可以直接导入使用的。

我推荐这款api管理工具是因为我觉着文档很干净，面对一款舒适的管理工具，工作起来当然就事半功倍了。下面是我的实际项目截图

easydoc

EasyDoc，简单、快速生成文档的工具。仅仅一个软件文件搞定！随带随用，不用安装，更不用其它依赖。支持微软、苹果、Linux等操作系统。

网址：https://easydoc.xyz/

是不是官网是清爽的感觉，原谅笔者是一个颜值控。

easydoc也是分为免费版和企业版，这里我给大家推荐工具，具体怎么使用就看大家的喜好了。

showdoc

一个非常适合IT团队的在线API文档、技术文档工具。你可以使用Showdoc来编写在线API文档、技术文档、数据字典、在线手册

网址：https://www.showdoc.com.cn/

我在最初写接口是用的showdoc，后来公司中换成了apizza，不过showdoc的功能非常强大，不仅可以编写api接口文档，还可以书写数据库字典，这个功能对于程序员二次开发来说绝对是最大的福音。

当然除此之外，showdoc是支持源码下载的，也就是说你可以将本套代码部署在自己的服务器上，不必担心托管在三方服务器的风险，并且也没有项目以及接口的限制，值得强烈推荐。

综上所述，列举了三款笔者认为比较好的api管理工具，肯定工具不止这三种，有其他大家更喜爱的api管理文档，大家可以一块在评论区讨论。

需要小程序软件开发的可以联系我，可提供完整开发流程服务，谢谢。

我们知道在项目开发阶段，接口文档基本上是必备产物了，一般由后端开发人员提供，作为和前端人员进行前后端接口联调的桥梁，或者与别的项目模块进行交互提供指导等等，接口文档的准确性，实时性，详细与否等，都会极大的影响前面的操作。那么如何才能优雅的生成接口文档呢？

其实对于做开发的大多数人来说，多多少少都听过swagger，它是一个较为流行的接口文档管理工具，使用起来非常方便。所以大多数人都会使用swagger来生成接口文档，但是今天我要介绍另外一种生成接口文档的方式。通过swagger插件(如jar包)解析编写了接口注解的java代码, 而后通过生成的swagger.json文件解析出接口信息并导入接口文档管理工具yapi（yapi是去哪儿的大前端团队开发，基于react+antd的一套接口文档管理工具）。具体操作步骤如下：

编写注解

图中的@POST, @ApiResponses, @Path等意思都很明显，因为我的java只有一点点语法基础, 所以理解可能有点出入, 我这里简单理解为注释的意思。如有不对求指教。

这个类里面, 有user和login属性, 分别给属性加了类似这样的注解

通过注解生成swagger.json

解决好pom文件的依赖后。在项目目录执行:mvn clean compile

导入yapi

yapi是去哪儿的大前端团队开发，基于react+antd的一套接口文档管理工具，可以自己下载体验下，真心不错。至于不需要yapi, 钟爱原生swagger的童鞋, 也可以直接将swagger.json放入你的本地swaggerUI中查看接口文档。

当然这种方法有个缺点就是开发需要在每个model的类加上注解, 写每一个接口也需要注解，这里只是提供另外一种生成接口的思路。

如果觉得笨猫的回答对你有用，点个关注谢谢。

后端接口文档

首先从后端来说，目前使用比较广泛的就是Swagger，可以说是大部分后端开发者首选的接口文档生产工具，对于生产的接口描述详尽，清晰，甚至可以通过接口文档服务来验证接口！

那么其配置来说也相对的简单易用，这也是其为什么受到了众多后端开发者喜爱的原因，当然了Swagger不仅仅支持java，还支持多种语言，而且目前主流的语音对于Swagger的支持也已经做的非常好了！

前端接口文档

那么对于前端来说，因为笔者就是一名从业7年的前端工程师，那么前端的接口文档，笔者还是比较喜欢一款工具的叫docsify，这款文档是一款直接MarkDown语法进行生成文档，而且目前所有知名的前端框架采用的文档大部分也都是通过docsify工具进行生成！

那么这款工具的好处就是你编写的MarkDown语法可以在任何markdown语法浏览工具上进行识别，同时markdown语法也是比较简单，减小了额外学习语法的负担，是一款非常不错的工具，笔者在这里也强烈建议前端从业者可以尝试一下这个工具。

以上就是笔者分享的两款目前主流的接口文档工具，个人感觉生成的文档都是比较优雅和易懂的，而且排版布局都是非常良好。

我是路飞写代码，欢迎关注我，一切分享知识，共同进步，欢迎留言！

优雅的自动生成接口文档

我下来介绍几种我Java项目中常用的，今天我们只讲脉络，详细使用方法，去某度搜：

1.集成swagger，使用注解生成，自动生成接口文档

2.集成apiDoc，在源代码中通过创建API注释从而自动生成api说明文档

3.集成knife4f,knife4j是为Java MVC框架集成Swagger生成Api文档的工具,前身是swagger-bootstrap-ui

以上三个都不难，主要是你要知道，有哪些插件可以干这些事，用起来都请简单的，我个人建议使用注释ApiDoc，无侵入式编程，我们的代码就不会显得很杂乱，同时培养我们规范注释的书写。

一个帮给您思路和建议的全栈开发工程师，欢迎留言讨论，私信也可以哦，记得加关注哦！

对于在线帮助文档的生成，我一直在找一个类似开源的工具来做这个事情，需求实际很简单，就是能够很方便的编辑和生成在线帮助文档，API接口帮助文档，同时需要支持Markdown编辑器。在我1年多前在网上搜索的时候，当时实际没有找到比较合适的工具，今天再做下整理。

ShowDoc-在线文档生成工具

地址：http://blog.star7th.com/2015/11/1816.html

简单来说，ShowDoc是一个非常适合IT团队的在线文档分享工具，当然也适合用于制作业务系统的在线帮助文档，制作API接口文档。同时对于ShowDoc来说本身又做了些定制，即除了我们日常的在线帮助文档外，还支持制作API接口文档，数据库设计的数据字典类文档的生成。

对于详细的功能和特点介绍可以参考上面网址和Demo，其中比较重要的有两点：

其一：支持MarkDown编辑器，符合前面我谈到的一个关键需求。

其二：对于API接口文档，数据字典类文档支持模板插入，方便对这类文档进行编辑。

ShowDoc遵循Apache2开源协议发布，并提供免费使用。

请参考：

http://blog.star7th.com/2016/05/2007.html

如果你没有自己的服务器，你可以使用在线的ShowDoc http://www.showdoc.cc。

易文档：https://easydoc.xyz/#/

这个是商用的一个产品，有免费版本但是功能很弱，也是完全支持Markdown语法。

易文档让您轻松编写和维护高质量的文档。 从需求文档、API文档、部署文档到使用手册，多种定制文档编辑器，满足您整个开发周期需求； 支持接口在线测试，一键生成文档、调用示例、mock配置。 极致的编写体验，优雅的排版，让文档成为一种乐趣。

核心能力包括：

a. 快速编写：常用参数一键引用，支持Json导入，一键生成文档、调用示例、Mock

b. 支持导出：可导出PDF、HTML、WORD、JSON

c. 自定义模板：可灵活自定义文档结构，存为模板，定制专属模板

d. 接口测试：在线接口测试，可把测试结果存为调用示例、一键生成文档

可以看到这个商用版本的能力还是相当强，特别是对API接口文档的支持能力。整体的编辑功能易用性也不错，而且支持在线预览，支持各种导入。即使对于一个企业来说完全私有化部署费用也不贵。是值得推荐的一款在线文档编写和生成工具产品。

MinDoc接口文档在线管理系统 https://www.iminho.me/

MinDoc 的前身是 SmartWiki 文档系统。SmartWiki 是基于 PHP 框架 laravel 开发的一款文档管理系统。因 PHP 的部署对普通用户来说太复杂，所以改用 Golang 开发。可以方便用户部署和实用，同时增加Markdown和HTML两种编辑器。

该系统基本可以用来储存日常接口文档，数据库字典，手册说明等文档。内置项目管理，用户管理，权限管理等功能，能够满足大部分中小团队的文档管理需求。从网站看主要功能包括：

项目管理，可以对项目进行编辑更改，成员添加等。

文档管理，添加和删除文档，文档历史恢复等。

用户管理，添加和禁用用户，个人资料更改等。

用户权限管理 ， 实现用户角色的变更。

项目加密，可以设置项目公开状态，私有项目需要通过Token访问。

站点配置，二次开发时可以添加自定义配置项。

附件管理，可管理所有项目中上传的文件。

项目导出，目前支持导出 PDF、Word、EPUB、MOBI、Markdown 等格式项目。

标签管理，可关系已存在的项目标签

导入项目，支持导入Markdown压缩包成为一个项目

二级目录部署，支持将 MinDoc 部署到二级子目录

具体帮助参考：https://www.iminho.me/wiki/docs/mindoc/mindoc-summary.md

该项目本身开源，整体感觉简洁易用，也比较适合用于做业务系统的在线帮助文档，而且整体界面风格简洁，也方便和业务系统本身进行集成。

APIPost工具： https://www.apipost.cn/

ApiPost是一个支持团队协作，并可直接生成文档的API调试、管理工具。支持模拟POST、GET、PUT等常见请求，是后台接口开发者或前端、接口测试人员不可多得的工具 。支持接口调试的同时快速生成、一键导出各种格式的api文档。开发、测试人员再也不用头疼接口文档的编写。

该产品同样有免费版本和商用版本，而且不仅仅提供API接口文档的生成能力，额外也提供了API接口的自动化测试和管理能力，方便团队和研发协同。

在应用开发过程中经常需要对其他应用或者客户端提供 RESTful API 接口，尤其是在版本快速迭代的开发过程中，修改接口的同时还需要同步修改对应的接口文档，这使我们总是做着重复的工作，并且如果忘记修改接口文档，就可能造成不必要的麻烦。

为了解决这些问题，Swagger 就孕育而生了，那让我们先简单了解下。

Swagger 简介

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

总体目标是使客户端和文件系统作为服务器，以同样的速度来更新。文件的方法、参数和模型紧密集成到服务器端的代码中，允许 API 始终保持同步。

下面我们在 Spring Boot 中集成 Swagger 来构建强大的接口文档。

Spring Boot 集成 Swagger

Spring Boot 集成 Swagger 主要分为以下三步：

1. 加入 Swagger 依赖
2. 加入 Swagger 文档配置
3. 使用 Swagger 注解编写 API 文档

加入依赖

首先创建一个项目，在项目中加入 Swagger 依赖，项目依赖如下所示：

加入配置

接下来在 config 包下创建一个 Swagger 配置类 Swagger2Configuration，在配置类上加入注解 @EnableSwagger2，表明开启 Swagger，注入一个 Docket 类来配置一些 API 相关信息，apiInfo() 方法内定义了几个文档信息，代码如下：

列举其中几个文档信息说明下：

• title：接口文档的标题
• description：接口文档的详细描述
• termsOfServiceUrl：一般用于存放公司的地址
• version：API 文档的版本号
• contact：维护人、维护人 URL 以及 email
• license：许可证
• licenseUrl：许可证 URL

编写 API 文档

在 domain 包下创建一个 User 实体类，使用 @ApiModel 注解表明这是一个 Swagger 返回的实体，@ApiModelProperty 注解表明几个实体的属性，代码如下（其中 getter/setter 省略不显示）：

最后，在 controller 包下创建一个 UserController 类，提供用户 API 接口（未使用数据库），代码如下：

启动项目，访问 http://localhost:8080/swagger-ui.html，可以看到我们定义的文档已经在 Swagger 页面上显示了，如下图所示：

到此为止，我们就完成了 Spring Boot 与 Swagger 的集成。

同时 Swagger 除了接口文档功能外，还提供了接口调试功能，以创建用户接口为例，单击创建用户接口，可以看到接口定义的参数、返回值、响应码等，单击 Try it out 按钮，然后点击 Execute 就可以发起调用请求、创建用户，如下图所示：

注解介绍

由于 Swagger 2 提供了非常多的注解供开发使用，这里列举一些比较常用的注解。

@Api

@Api 用在接口文档资源类上，用于标记当前类为 Swagger 的文档资源，其中含有几个常用属性：

• value：定义当前接口文档的名称。
• description：用于定义当前接口文档的介绍。
• tag：可以使用多个名称来定义文档，但若同时存在 tag 属性和 value 属性，则 value 属性会失效。
• hidden：如果值为 true，就会隐藏文档。

@ApiOperation

@ApiOperation 用在接口文档的方法上，主要用来注解接口，其中包含几个常用属性：

• value：对API的简短描述。
• note：API的有关细节描述。
• esponse：接口的返回类型（注意：这里不是返回实际响应，而是返回对象的实际结果）。
• hidden：如果值为 true，就会在文档中隐藏。

@ApiResponse、@ApiResponses

@ApiResponses 和 @ApiResponse 二者配合使用返回 HTTP 状态码。@ApiResponses 的 value 值是 @ApiResponse 的集合，多个 @ApiResponse 用逗号分隔，其中 @ApiResponse 包含的属性如下：

• code：HTTP状态码。
• message：HTTP状态信息。
• responseHeaders：HTTP 响应头。

@ApiParam

@ApiParam 用于方法的参数，其中包含以下几个常用属性：

• name：参数的名称。
• value：参数值。
• required：如果值为 true，就是必传字段。
• defaultValue：参数的默认值。
• type：参数的类型。
• hidden：如果值为 true，就隐藏这个参数。

@ApiImplicitParam、@ApiImplicitParams

二者配合使用在 API 方法上，@ApiImplicitParams 的子集是 @ApiImplicitParam 注解，其中 @ApiImplicitParam 注解包含以下几个参数：

• name：参数的名称。
• value：参数值。
• required：如果值为 true，就是必传字段。
• defaultValue：参数的默认值。
• dataType：数据的类型。
• hidden：如果值为 true，就隐藏这个参数。
• allowMultiple：是否允许重复。

@ResponseHeader

API 文档的响应头，如果需要设置响应头，就将 @ResponseHeader 设置到 @ApiResponse 的 responseHeaders 参数中。@ResponseHeader 提供了以下几个参数：

• name：响应头名称。
• description：响应头备注。

@ApiModel

设置 API 响应的实体类，用作 API 返回对象。@ApiModel 提供了以下几个参数：

• value：实体类名称。
• description：实体类描述。
• subTypes：子类的类型。

@ApiModelProperty

设置 API 响应实体的属性，其中包含以下几个参数：

• name：属性名称。
• value：属性值。
• notes：属性的注释。
• dataType：数据的类型。
• required：如果值为 true，就必须传入这个字段。
• hidden：如果值为 true，就隐藏这个字段。
• readOnly：如果值为 true，字段就是只读的。
• allowEmptyValue：如果为 true，就允许为空值。

到此为止，我们就介绍完了 Swagger 提供的主要注解。

总结

Swagger 可以轻松地整合到 Spring Boot 中构建出强大的 RESTful API 文档，可以减少我们编写接口文档的工作量，同时接口的说明内容也整合入代码中，可以让我们在修改代码逻辑的同时方便的修改接口文档说明，另外 Swagger 也提供了页面测试功能来调试每个 RESTful API。

如果项目中还未使用，不防尝试一下，会发现效率会提升不少。

本文的完整代码在 https://github.com/wupeixuan/SpringBoot-Learn 的 interface-doc 目录下。

关于如何优雅的生成接口文档，我觉得在于“优雅”二字，那么要怎么做到“优雅”？

要能够解决以下问题：

1. 相信无论是前端开发还是后端开发，都有被接口文档折磨的经历；前端经常抱怨后端给的接口文档与实际情况不一致，后端觉得编写和维护接口文档太耗时间，经常来不及更新；

2. 前后端联调，因为前端输入数据的不符合，耗费大量时间和精力解决这个问题，结果只是因为数据问题，白白浪费了时间

解决方案

1.如果项目启动阶段，就已经搭好了后台框架，那可以直接编写服务端代码（即controller及其入参出参对象），然后通过Springfox－swagger 生成swagger json描述文件

如果项目启动阶段并没有相关后台框架，而前端对接口文档追得紧，那就建议先编写swagger描述文件，通过该描述文件生成接口文档。后续后台框架搭好了，也可以生成相关的服务端代码。

2.项目迭代阶段事情就简单很多了。后续后台人员，无需关注Swagger描述文件和接口文档，有需求变更导致接口变化，直接写代码就好了。把调用层的代码做个修改，然后生成新的描述文件和接口文档后，给到前端即可。真正做到了一劳永逸

以上1和2两个方案能够做到代码和接口文档的一致性，服务端开发再也不用花费精力去维护接口文档。

3.通过适当地在代码中加入swagger的注解，可以让你的接口文档描述信息更加详细

如下相关代码示例及效果图：

4.在提供接口文档的同时，把所有接口的模拟请求响应数据也提供给前端

如下是请求参数对象的模拟数据：

模拟请求数据报文效果图：

如下是响应模拟数据：

响应模拟数据报文效果图：

以上3和4两个方案将会提高前端的开发效率，减少许多发生在联调时候才会发生的问题。

对于前后端来说，都能够提供方便，就是一篇好的“优雅”的接口文档！！

说到优雅的接口文档，很多人不免都想到了Swagger，但是Swagger真的好吗？众所周知，这个框架对代码有很大的侵入性，况且需要程序员自行开发，甚至可能会出现30分钟开发完业务，1个小时写Swagger注解的情况。

所以，Swagger不能被称之为优雅。那么，就不得不说一下YApi了。

YAPI，专为接口管理而生，友好的接口文档，基于websocket的多人协作接口编辑功能和类postman测试工具，让多人协作成倍提升开发效率。支持MockServer，基于Mock.js，使用简单而功能强大。

项目管理

YAPI可以添加分组，可以为每个分组设置组长，组员，其他人无权限访问该分组。然后，分组内可创建项目，可定义基本路径，其实，可以简单理解为api接口的固定前缀，不单单指上下文根。例如，可以为 /shop/api 等。

创建接口

项目创建完成后，即可进入详情页进行后续操作。

创建接口也比较简单，其内容通俗易懂，直接填写即可。

在设置界面，可对项目及接口进行相关设置，如域名等，也可以设置域名为本地。

还可以查看项目的动态，也就是变动日志。

如果你之前做过Swagger的集成，那么，在这里可以直接导入，不必一一创建，既贴心又方便。

还可以开发一个wiki，方便接口使用者及开发者了解项目详情，接口逻辑。

当然了，如果团队成员发生变动，如新进人员、离职人员等，可以再次对项目成员进行管理。

另外，还支持MOCK配置、环境配置、全局MOCK脚本、Swagger自动同步等。

介绍至此，大家已然明白，相较于Swagger，YAPI对系统的侵入，可以说是零。也很符合其优雅的接口管理系统美名。

关于其他更详细的使用方面的问题，大家可下载部署安装之后，亲自尝试尝试，即可领略其魅力。

关注@银河架构师，发现更多精彩内容。

做golang开发的，基于代码模板和ast语法树自己写了一个接口文档工具，感觉效率高，贴合实际场景。

可以用 useMock 在线 mock 接口并自动生成接口文档，带接口统计，支持团队协作，我们一直在使用