什么？你还在用Postman，快来试试这些API管理工具吧！

文章目录

概要

随着互联网的普及和发展，API 接口已经无处不在。它已经在 Web 应用程序、移动应用程序、云计算、物联网、人工智能等领域中得到广泛应用。
作为一名合格的程序员，不仅需要有较高的代码能力，还需要有高效的接口对接能力，掌握一门接口文档管理工具可以让你的接口对接工作事半功倍。下面我将结合代码为大家奉上几款高效的实战工具。

内容

Java Doc

javaDoc是JDK提供的一款用于便携编写java文档的工具。通过在类、成员变量上编写javadoc文档，从而生成清晰易读的api文档。(推荐指数★)

优点

1. 原生java的API管理工具，Javadoc根据标准的Javadoc注释生成；
2. 成熟，简单，对代码无侵入性；
3. 代码、注释、文档一体化。

缺点

1. 在项目中，难以规范化，统一化；
2. 对于新人来说，上手的难度不小。

实现

1. 单击Tools->点击Generate JaavaDoc

1. 设置四个东西

• 生成指定的文件
• 指定的路径
• Locale: zh_CN
• Other command line arguments:-encoding UTF-8 -charset UTF-8 -windowtitle “接口文档3.4” -link http://docs.Oracle.com/javase/7/docs/api

1. 即可生成Javadoc文档

应用场景

• 我们更多面向类库开发者、项目内部使用。提供给外部调用的一个接口查询、使用示例清单。

Swagger

Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。(推荐指数★★★)

优点

1. 节省了大量手写接口文档的时间；
2. 生成的接口文档可以直接在线测试，省去了使用 Postman 设置接口参数的过程，而且请求参数，返回参数一目了然；
3. 接口按照模块已经分类好了，很清晰。

缺点

1. 代码侵入率高，需要添加大量注解；
2. 对于返回结果不能添加说明或者实现这个功能非常麻烦；
3. 无法测试错误的请求方式、参数等。

实现

1.添加依赖

<!--依赖管理 --><dependencies><dependency><!--添加Swagger依赖 --><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.9.2</version></dependency><dependency><!--添加Swagger-UI依赖 --><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.9.2</version></dependency></dependencies>

注意：swagger版本和spring版本应该匹配使用，我这里用的是2.3.2.RELEASE版本的springboot（3.1.1版本报错，其他版本没有校验）

2.添加配置类

packagecom.chaoge.doc.config;importorg.springframework.context.annotation.Bean;importorg.springframework.context.annotation.Configuration;importspringfox.documentation.builders.ApiInfoBuilder;importspringfox.documentation.builders.RequestHandlerSelectors;importspringfox.documentation.service.ApiInfo;importspringfox.documentation.spi.DocumentationType;importspringfox.documentation.spring.web.plugins.Docket;importspringfox.documentation.swagger2.annotations.EnableSwagger2;/**
 * Swagger配置类
 *
 * @author chaogebucai
 * @date 2023/6/29 11:10
 */@Configuration@EnableSwagger2publicclassSwaggerConfig{@BeanpublicDocketcustomDocket(){returnnewDocket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.basePackage("com.chaoge.doc.controller")).build();}privateApiInfoapiInfo(){returnnewApiInfoBuilder().title("超哥不才").description("超哥不才演示Swagger接口文档工具").version("1.0.0").build();}}

注意：这里可以更改扫描路径以及扫描类型，建议在MVC架构中使用controller包路径扫描。

3.添加API注解

packagecom.chaoge.doc.controller;importcom.chaoge.doc.base.AjaxResult;importio.swagger.annotations.Api;importio.swagger.annotations.ApiImplicitParam;importio.swagger.annotations.ApiOperation;importorg.springframework.web.bind.annotation.GetMapping;importorg.springframework.web.bind.annotation.RequestMapping;importorg.springframework.web.bind.annotation.RestController;/**
 * Swagger接口文档测试控制层
 *
 * @author chaogebucai
 * @date 2023/6/29 11:12
 */@RestController@RequestMapping("/swagger")@Api(tags ="Swagger接口文档测试")publicclassSwaggerController{/**
     * swagger接口文档测试接口
     *
     * @return 结果集
     */@GetMapping("/test")@ApiOperation("测试接口")@ApiImplicitParam(name ="id",value ="测试ID",dataType ="int")publicAjaxResult<Object>swagerTest(int id){returnnewAjaxResult<>(id);}}

Swagger2 基本使用：
@Api 描述类/接口的主要用途
@ApiOperation 描述方法用途
@ApiImplicitParam 描述方法的参数
@ApiImplicitParams 描述方法的参数(Multi-Params)
@ApiIgnore 忽略某类/方法/参数的文档

4.查阅文档
项目启动之后，访问http://localhost:8080/swagger-ui.html即可出现一下界面，由于时间关系，仅演示一条接口。

5.API测试

应用场景

1. 我们更多是在web项目中，尤其是restFul风格的前后端分离的项目，在设计、开发、测试阶段能带来极大的优势

JApiDocs

JApiDocs 是一个符合 Java 编程习惯的 Api 文档生成工具。最大程度地利用 Java 的语法特性，你只管用心设计好接口，添加必要的注释，JApiDocs 会帮你导出一份漂亮的 Html 文档，并生成相关的 Java 和 Object-C 相关数据模型代码，从此，Android 和 IOS 的同学可以少敲很多代码了，你也不需要费力维护接口文档的变化，只需要维护好你的代码就可以了。(推荐指数★★★★)

优点

1. 没有Swagger那样的侵入式注解，通过基本注释即可实现文档输出，简单明了；
2. 静态接口文档，可离线查看。

缺点

1. 界面单调缺乏美感，但是也足够用来做前后端交互；
2. 静态文档，更新需要同步对接方；
3. 不可以制定部分接口生成文档。

实现

1. 添加依赖

<dependency><groupId>io.github.yedaxia</groupId><artifactId>japidocs</artifactId><version>1.4</version></dependency>

1. 添加配置

DocsConfig config =newDocsConfig(); 
config.setProjectPath("your springboot project path");
config.setProjectName("ProjectName");
config.setApiVersion("V1.0");
config.setDocsPath("your api docs path");
config.setAutoGenerate(Boolean.TRUE);Docs.buildHtmlDocs(config);

1. 编写接口

packagecom.chaoge.doc.controller;importcom.chaoge.doc.base.AjaxResult;importio.github.yedaxia.apidocs.Docs;importio.github.yedaxia.apidocs.DocsConfig;importorg.springframework.web.bind.annotation.GetMapping;importorg.springframework.web.bind.annotation.RequestMapping;importorg.springframework.web.bind.annotation.RestController;/**
 * JapiDocs接口测试
 *
 * @author chaogebucai
 * @date 2023/6/29 14:50
 */@RestController@RequestMapping("/japidocs")publicclassJapiDocsController{/**
     * swagger接口文档测试接口
     *
     * @return 结果集
     */@GetMapping("/test")publicAjaxResult<Object>swagerTest(int id){returnnewAjaxResult<>(id);}/**
     * 运行main方法生成api文档到指定路径下
     * 
     * @param args
     */publicstaticvoidmain(String[] args){DocsConfig config =newDocsConfig();
        config.setProjectPath("D:\\project\\doc");
        config.setProjectName("japidocs测试文档");
        config.setApiVersion("V1.0");
        config.setDocsPath("D:\\japidocs");
        config.setAutoGenerate(Boolean.TRUE);Docs.buildHtmlDocs(config);}}

1. 查看文档 打开index.html即可

Easy API

easyapi是集自动生成、调试、管理于一身接口文档插件，拥有极强的代码环境适应能力，可以按需整合当下流行的接口文档框架，支持高度DIY，无论你是想基于注释，或者基于注解或者基于源码，easyapi都可以满足你，并拥有极度友好的页面操作效果。(推荐指数★★★★)

优点

1. easyapi可以做到零代码生成项目对应的接口文档；
2. 如果你的项目没有使用任何文档框架，没关系，easyapi会去扫描源码，通过读取注释生成标准的接口文档；
3. 如果你的项目没有使用任何文档框架，没关系，easyapi会去扫描源码，通过读取注释生成标准的接口文档；
4. 如果你的项目同时存在多套接口规范，你可能需要进行少量的代码配置，但最终easyapi会将多套规范全部兼容。

缺点

1. 去客户端创建一系列分组；
2. 学习成本较高。

实现

1. 添加依赖

<dependency><groupId>cn.easyutil</groupId><artifactId>easyapi</artifactId><version>0.7.7.2</version></dependency>

1. 添加配置

springboot配置文件添加easyapi.enable=true

1. 编写文档

packagecom.chaoge.doc.controller;importcom.chaoge.doc.base.AjaxResult;importorg.springframework.web.bind.annotation.GetMapping;importorg.springframework.web.bind.annotation.RequestMapping;importorg.springframework.web.bind.annotation.RestController;/**
 * easyapi文档测试
 *
 * @author chaogebucai
 * @date 2023/6/29 15:23
 */@RestController@RequestMapping("/easyapi")publicclassEasyapiController{/**
     * easyapi接口文档测试接口
     *
     * @return 结果集
     */@GetMapping("/test")publicAjaxResult<Object>easyapiTest(int id){returnnewAjaxResult<>(id);}}

1. 查看文档 6.使用文档 点击获取更多功能配置