接口文档Swagger+Knife4j的使用

一、Swagger简介

官网：https://swagger.io/

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

Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口，可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似，Swagger 消除了调用服务时可能会有的猜测。
 

二、Swagger使用教程

1.引入相关依赖

在Knife4j的官方文档中，springboot2.6版本以上的使用与Knife4j要使用4.0.0以上的版本，同时Swagger的版本要使用3.0.0以上；

但是在项目中，3.0.0的swagger包没有生效，仍旧用的2.9.2（待解决是否是包下载错误）

        <!-- swagger -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

2.自定义Swagger配置类

在config文件下新建SwaggerConfig       

package com.xxx.xxx.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @author: shayu
 * @date: 2022/11/20
 * @ClassName: yupao-backend01
 * @Description: 自定义 Swagger 接口文档的配置
 */
@Configuration // 配置类
@EnableSwagger2 // 开启 swagger2 的自动配置
public class SwaggerConfig {
    @Bean
    public Docket docket() {
        // 创建一个 swagger 的 bean 实例
        return new Docket(DocumentationType.SWAGGER_2)
                // 配置接口信息
                .select() // 设置扫描接口
                // 配置如何扫描接口
                .apis(RequestHandlerSelectors
                //.any() // 扫描全部的接口，默认
                //.none() // 全部不扫描
                .basePackage("com.xxx.xxx.controller") // 扫描指定包下的接口，最为常用
                //.withClassAnnotation(RestController.class) // 扫描带有指定注解的类下所有接口
                //.withMethodAnnotation(PostMapping.class) // 扫描带有只当注解的方法接口
                )
                .paths(PathSelectors
                .any() // 满足条件的路径，该断言总为true
                /.none() // 不满足条件的路径，该断言总为false（可用于生成环境屏蔽swagger）
                //.ant("/user/**") // 满足字符串表达式路径
                //.regex("") // 符合正则的路径
                )
                .build();
    }
    
    // 基本信息设置
    private ApiInfo apiInfo() {
        Contact contact = new Contact(
                "xxx", // 作者姓名
                "xxx.cn", // 作者网址
                "xxx@qq.com"); // 作者邮箱
        return new ApiInfoBuilder()
                .title("xxx系统-接口文档") // 标题
                .description("众里寻他千百度，慕然回首那人却在灯火阑珊处") // 描述
                .termsOfServiceUrl("https://www.baidu.com") // 跳转连接
                .version("1.0") // 版本
                .license("Swagger-的使用(详细教程)")
                .licenseUrl("https://blog.csdn.net/xhmico/article/details/125353535")
                .contact(contact)
                .build();
    }

}

3.配置yml文件

因为Springboot和Swagger版本的原因，需要在yml文件下配置

 

4.启动即可

 查看地址：http://localhost:8080/xxx/swagger-ui.html

 三、Knife4j简介

官方文档：快速开始 | Knife4j

 四、Knife4j使用教程

1.引入依赖

        <!-- knife4j 接口文档 -->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-gateway-spring-boot-starter</artifactId>
            <version>4.0.0</version>
        </dependency>

2.修改SwaggerConfig文件

package com.example.af.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @author: af
 */
@Configuration // 配置类
@EnableSwagger2 // 开启 swagger2 的自动配置
@Profile("dev")
public class SwaggerConfig {
    @Bean(value = "defaultApi2")
    public Docket defaultApi2() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                // 这里一定要标注你控制器的位置
                .apis(RequestHandlerSelectors.basePackage("com.xxx.xxx.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    // 基本信息设置
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("xxx")
                .description("xxx接口文档")
                .termsOfServiceUrl("https://github.com/afphenix")
                .contact(new Contact("af","https://af.cn/","af-fa@qq.com"))
                .version("1.0")
                .build();
    }
}

3.启动即可

地址：http://localhost:8080/xxx/doc.html#/home