Springboot集成swagger,使用apifox浏览

相信很多小伙伴还在手动编辑接口文档，是不是很痛苦，每次辛辛苦苦写完代码之后，还得写个测试代码来测试接口，测试完了又得写个接口文档方便前端同学对接，实在是难受的丫匹，swagger + apifox可以帮你干这些繁琐的事情。

首先在pom文件中先导入swagger依赖

        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-ui</artifactId>
            <version>1.6.11</version>
            <exclusions>
                <exclusion>
                    <artifactId>swagger-ui</artifactId>
                    <groupId>org.webjars</groupId>
                </exclusion>
            </exclusions>
        </dependency>

注意，依赖里面排除了swagger-ui，swagger-ui界面实在太难用了，很多年前的东西了，这里我推荐用apifox，apifox提供了简洁漂亮的ui界面，你可以下载apifox软件，也有网页版本。

上面集成了swagger之后，我们启动程序。访问http://127.0.0.1:8080/v3/api-docs，ip端口记得换成自己项目的哈，我这里用的127.0.0.1和8080，你会发现网页上出现一json字符串

这就是swagger根据你controller里面的接口的签名解析出来的（前提是你项目中创建了controller，空项目肯定是看不到的）。这是在网页上访问这个地址，我们到apifox中使用这个地址看看（在项目设置下面的导入数据选项）。

 

 url导入，点击提交就能看到如下页面

 这就是根据那串json字符串解析出来的，点击确认导入，在接口管理中就能看到这些接口了

 apifox还提供了在线测试功能

点击自动生成，会自动帮你填充参数，也可以自己编辑，然后运行就好了。有时候运行失败可以检查下环境，主要是ip端口，右上角的环境按钮可以管理环境，更改ip端口啥的。

 一般项目为了统一返回值管理。会定义一个Result类作为统一返回值，里面有code，data，message属性。

@Data
public class Result {
    private int code;
    private String message;

    private Object data;
    public Result() {}

    public Result(int code, String message) {
        this.code = code;
        this.message = message;
    }

    /**
     * 成功
     */
    public static Result success(Object data) {
        Result result = new Result();
        result.setCode(ResultMsgEnum.SUCCESS.getCode());
        result.setMessage(ResultMsgEnum.SUCCESS.getMessage());
        result.setData(data);
        return result;
    }
    /**
     * 失败
     */
    public static Result fail(int code, String message) {
        return new Result(code, message);
    }

    /**
     * 失败
     */
    public static Result fail(ResultMsgEnum) {
        return new Result(code, message);
    }
}

用了统一返回值后，你会发现接口文档不太好用了

 我这个data是能点开的，能看到里面具体的属性，如果使用统一返回值，这个data是一个固定类型object，这里是点不开的，那么每个接口的返回值都是一样的。那么怎么样才能让它能够点开呢？把Result类改造一下，加入泛型。

@Data
public class Result<T> {
    private int code;
    private String message;

    private T data;
    public Result() {}

    public Result(int code, String message) {
        this.code = code;
        this.message = message;
    }

    /**
     * 成功
     */
    public static <T> Result<T> success(T data) {
        Result<T> result = new Result<>();
        result.setCode(ErrorEnum.SUCCESS.getCode());
        result.setMessage(ErrorEnum.SUCCESS.getMessage());
        result.setData(data);
        return result;
    }
    /**
     * 失败
     */
    public static <T> Result<T> fail(int code, String message) {
        return new Result<>(code, message);
    }

    /**
     * 失败
     */
    public static <T> Result<T> fail(ErrorEnum errorEnum) {
        return new Result<>(errorEnum.getCode(), errorEnum.getMessage());
    }
}

controller中的接口返回值就是这样的了，带上了泛型

 这时候在apifox中就能看到统一返回值中data里面的属性了。

再也不为写接口文档而烦恼了！！！

最后附上apifox操作文档：帮助中心 | Apifox 使用文档