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

超哥不才

已于 2023-06-29 15:46:21 修改

阅读量1.3k

点赞数

文章标签： java 测试工具

于 2023-06-29 15:43:43 首次发布

本文链接：https://blog.csdn.net/weixin_47560550/article/details/131451103

版权

文章目录

概要

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

在这里插入图片描述

内容

Java Doc

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

优点

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

缺点

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

实现

单击Tools->点击Generate JaavaDoc

在这里插入图片描述

设置四个东西

生成指定的文件
指定的路径
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

即可生成Javadoc文档

应用场景

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

Swagger

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

优点

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

缺点

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

实现

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.添加配置类

package com.chaoge.doc.config;
 
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * Swagger配置类
 *
 * @author chaogebucai
 * @date 2023/6/29 11:10
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig{

    @Bean
    public Docket customDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.chaoge.doc.controller"))
                .build();
    }
 
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("超哥不才")
                .description("超哥不才演示Swagger接口文档工具")
                .version("1.0.0")
                .build();
    }
}

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

3.添加API注解

package com.chaoge.doc.controller;

import com.chaoge.doc.base.AjaxResult;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * Swagger接口文档测试控制层
 *
 * @author chaogebucai
 * @date 2023/6/29 11:12
 */
@RestController
@RequestMapping("/swagger")
@Api(tags = "Swagger接口文档测试")
public class SwaggerController {

    /**
     * swagger接口文档测试接口
     *
     * @return 结果集
     */
    @GetMapping("/test")
    @ApiOperation("测试接口")
    @ApiImplicitParam(name = "id",value = "测试ID",dataType = "int")
    public AjaxResult<Object> swagerTest(int id){
        return new AjaxResult<>(id);
    }
}

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

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

5.API测试
在这里插入图片描述

应用场景

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

JApiDocs

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

优点

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

缺点

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

实现

添加依赖

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

添加配置

DocsConfig config = new DocsConfig(); 
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);

编写接口

package com.chaoge.doc.controller;

import com.chaoge.doc.base.AjaxResult;
import io.github.yedaxia.apidocs.Docs;
import io.github.yedaxia.apidocs.DocsConfig;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * JapiDocs接口测试
 *
 * @author chaogebucai
 * @date 2023/6/29 14:50
 */
@RestController
@RequestMapping("/japidocs")
public class JapiDocsController {

    /**
     * swagger接口文档测试接口
     *
     * @return 结果集
     */
    @GetMapping("/test")
    public AjaxResult<Object> swagerTest(int id){
        return new AjaxResult<>(id);
    }

    /**
     * 运行main方法生成api文档到指定路径下
     * 
     * @param args
     */
    public static void main(String[] args) {
        DocsConfig config = new DocsConfig();
        config.setProjectPath("D:\\project\\doc");
        config.setProjectName("japidocs测试文档");
        config.setApiVersion("V1.0");
        config.setDocsPath("D:\\japidocs");
        config.setAutoGenerate(Boolean.TRUE);
        Docs.buildHtmlDocs(config);
    }
}

查看文档
打开index.html即可

Easy API

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

优点

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

缺点

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

实现

添加依赖

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

添加配置

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

编写文档

package com.chaoge.doc.controller;

import com.chaoge.doc.base.AjaxResult;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * easyapi文档测试
 *
 * @author chaogebucai
 * @date 2023/6/29 15:23
 */
@RestController
@RequestMapping("/easyapi")
public class EasyapiController {

    /**
     * easyapi接口文档测试接口
     *
     * @return 结果集
     */
    @GetMapping("/test")
    public AjaxResult<Object> easyapiTest(int id){
        return new AjaxResult<>(id);
    }
}