Swagger和Knife4j 接口文档

接口文档是什么？

当涉及到后端开发时，接口文档是非常重要的。接口文档是对系统中各种接口的定义、描述和说明的文档。这些接口可以是应用程序之间的通信接口，也可以是前端与后端之间的交互接口。

接口文档通常包括以下内容：

1. 接口的名称和描述：每个接口的名称和简要描述，以便开发人员了解其作用。
2. 请求参数：描述每个接口所需的请求参数，包括参数名称、数据类型、是否必需等信息。
3. 响应参数：描述每个接口返回的参数，包括参数名称、数据类型等信息。
4. 接口示例：提供一些示例请求和响应，帮助开发人员更好地了解接口的使用方式。
5. 接口调用规则：指定如何调用接口，例如请求方式（GET、POST等）、请求地址、认证方式等。

接口文档一般是后端开发人员写的。

常见的接口文档工具:

常见的接口文档工具包括Swagger、Postman、Apiary等，它们提供了友好的界面和便捷的功能，帮助开发人员管理和维护接口文档。

Swagger和Knife4j的介绍：

使用Swagger你只需要按照它的规范去定义接口及接口相关的信息，就可以做到生成接口文档，以及在线接口调试页面。 官网：https://swagger.io/

Knife4j 是为Java MVC框架集成Swagger生成Api文档的增强解决方案。

Swagger和Knife4j的作用：

通过Swagger可以帮助后端生成接口文档，并且可以进行在线接口测试

因为Knife4j是Swagger，所以现在基本上也就是用Knife4j

Knife4j的基本使用：

依旧还是老规矩：先放一个Knife4j的官网

快速开始 | Knife4j (xiaominfo.com)

1：引入依赖：

在引入依赖之前，我们需要知道：

所以我们引入的依赖是：

            <dependency>
                <groupId>com.github.xiaoymin</groupId>
                <artifactId>knife4j-spring-boot-starter</artifactId>
                <version>${knife4j}</version>
            </dependency>

2：在配置类中加入 knife4j 相关配置：

    /**
     * 通过knife4j生成接口文档
     * @return
     */
    @Bean
    public Docket docket() {
        ApiInfo apiInfo = new ApiInfoBuilder()
                .title("苍穹外卖项目接口文档")
                .version("2.0")
                .description("苍穹外卖项目接口文档")
                .build();
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.sky.controller"))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }

这里有一个注意点：

就是要将knife4j生成接口文档的包改成你的Controller

3：设置静态资源映射，否则接口文档页面无法访问：

1：第一种方式：

    /**
     * 设置静态资源映射
     * @param registry
     */
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

 2：第二种方式：

在application.yml中配置如下信息：

  spring:   
    mvc:
        pathmatch:
          matching-strategy: ant_path_matcher

结果展示：

 如何隐藏自己的接口文档：

看到这个标题可能会有点懵？为什么我们还要隐藏自己的接口文档

主要作用就是要保证自己项目的安全，首先，我们如果将项目上线，用户可以访问到我们的接口文档，那我们的项目信息可能就会泄露，所以我们需要用到springboot里面的一个注解在多环境的情况下隐藏我们的接口文档

如果不清楚多环境是什么的话：项目部署（前后端）_前后端项目部署-优快云博客

下面来写怎么将自己的接口文档隐藏：

可以通过在 SwaggerConfig 配置文件开头加上 @Profile({"dev", "test"}) 限定配置仅在部分环境开启

1：做好相关配置：

首先我们需要在配置中添加默认的环境：

2：用@Profile进行版本控制：

上述代码指定了这个环境为dev

启动项目之后控制台也会有提示信息： 

我们可以看到这个页面是可以了。

接下来当我们把这个@Profile注解后面的内容换成"prod"

这里有一个小坑：

就是Knife4j的依赖版本也会影响到上面的隐藏：

我一开始是

        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>3.0.2</version>
        </dependency>

3.x版本，这个版本有点奇怪，我按照上面的步骤进行改动之后，如果我把@Profile注解里面的内容改成不是dev，这个接口文档还是可以访问，太离谱了mad

后面去查了一下，好像需要配置knife4j的其它属性

 以后引入依赖的话还是低版本的稳定一点

Swagger和Apifox：

1、Apifox是设计阶段使用的工具，管理和维护接口

2、Swagger 在开发阶段使用的框架，帮助后端开发人员做后端的接口测试

我的理解是：

Apifox主要是用在还没有这个接口，我们需要去设计使用使用的工具

Swagger是在设计好接口之后，后端进行开发的时候使用的测试工具。

就直接访问异常

Swagger常用注解：

通过注解可以控制生成的接口文档，使接口文档拥有更好的可读性，常用注解如下：

@Api和@ApiOperationl作用：

先放一张不加注解的接口文档图

然后在类上加上@Api注解：

在两个方法上加上@ApiOperationl注解：

加完之后的效果图：

@ApiModel作用效果：

同样这个是没作用之前的：

在这个DTO类上加上了注释之后：

就有了注解解释。

@ApiModelProperty的作用效果：

这个作用在属性上，我的理解差不多就是作用在变量上，对一些变量进行说明。

还是上一个没注解的图：

在变量上加了注解之后：

Swagger管理不同路径的接口：

当我的项目开发到不同的路径（管理端和服务端）的时候，需要请求不同的路径，如果把两个接口的操作全放在一起的话，不便于管理。

    /**
     * 通过knife4j生成接口文档
     * @return
     */
    @Bean
    public Docket docket1() {
        log.info("生成接口文档");
        ApiInfo apiInfo = new ApiInfoBuilder()
                .title("苍穹外卖项目接口文档")
                .version("2.0")
                .description("苍穹外卖项目接口文档")
                .build();
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .groupName("服务端接口")
                .apiInfo(apiInfo)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.sky.controller.admin"))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }

    @Bean
    public Docket docket2() {
        log.info("生成接口文档");
        ApiInfo apiInfo = new ApiInfoBuilder()
                .title("苍穹外卖项目接口文档")
                .version("2.0")
                .description("苍穹外卖项目接口文档")
                .build();
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .groupName("用户端接口")
                .apiInfo(apiInfo)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.sky.controller.user"))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }

在这里加上这个分组名称之后，

在接口文档中就可以显示：

这种效果，遍历管理。