1.导入依赖jar包

<!-- web服务 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!--swagger3-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

2.配置SwaggerConfig

import io.swagger.annotations.ApiOperation;
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.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

/**
 * @author 尹稳健~
 * @version 1.0
 * @time 2022/9/6
 */
@Configuration
@EnableOpenApi
public class SwaggerConfig {

    /**
     * 创建API
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)
                // 是否启用swagger
                .enable(true)
                //用来创建该API的基本信息，展示在文档的页面中（自定义展示的信息）
                .apiInfo(apiInfo())
                // 设置哪些接口暴露给Swagger展示
                .select()
                // 扫描所有有注解的api，用这种方式更灵活
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                // 扫描所有包中的swagger注解
                .paths(PathSelectors.any())
                .build();

    }

    /**
     * 添加摘要信息
     */
    public ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // 设置标题
                .title("标题：尹稳健管理系统_Swagger3接口文档")
                // 描述
                .description("尹稳健无敌第一帅~")
                .contact(new Contact("yinwenjian", null, null))
                // 作者信息
                .version("v1.0")
                // 版本
                .build();
    }
}

3.直接启动（埋雷）

org.springframework.context.ApplicationContextException: Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException

这里我们发现启动报错了，解决方案:

在application.yml中配置

# Springfox使用的路径匹配是基于AntPathMatcher的，
#而Spring Boot 2.6.X使用的是PathPatternMatcher。
spring:
	mvc:
		pathmatch:
			matching-strategy: ant_path_matcher

运行成功！访问 http://localhost:8080/sky/swagger-ui/ 得到：

在这里插入图片描述

如果你没有写接口的话那么你肯定是比我少一个测试接口类的，下面是我的代码：

package com.sky.controller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * @author 尹稳健~
 * @version 1.0
 * @time 2022/9/6
 */
@Api(tags = "测试接口类")
@RestController
public class HelloController {

    @ApiOperation("测试hello")
    @PostMapping("/hello")
    public String hello(){
        return "hello";
    }
}

额。。。说实话，我感觉swagger3自带的这个页面挺丑的，所以我们可以给他改个样式：

4.修改swagger3前端样式：

<!--swagger3 ui 界面 个人喜好-->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-ui</artifactId>
    <version>3.0.3</version>
</dependency>

访问 http://localhost:8080/sky/doc.html 得到

在这里插入图片描述

总结：

  • swagger3配置SpringBoot高版本会出现错误，只需要在yml配置中加入配置
  • swagger3默认的访问地址是 http://localhost:8080/sky/swagger-ui/ 改了他的样式后，访问的地址是 http://localhost:8080/sky/doc.html

5.扩展

配置swagger发送请求每次携带token，因为一般后端项目都有用到安全框架，比如现在很火的SpringSecurity或者Shiro

在swagger配置中配置：

package com.sky.config;

import io.swagger.annotations.ApiOperation;
import io.swagger.models.auth.In;
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.oas.annotations.EnableOpenApi;
import springfox.documentation.service.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;

import java.util.ArrayList;
import java.util.List;

/**
 * @author 尹稳健~
 * @version 1.0
 * @time 2022/9/6
 */
@Configuration
@EnableOpenApi
public class SwaggerConfig {

    /**
     * 创建API
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)
                // 是否启用swagger
                .enable(true)
                //用来创建该API的基本信息，展示在文档的页面中（自定义展示的信息）
                .apiInfo(apiInfo())
                // 设置哪些接口暴露给Swagger展示
                .select()
                // 扫描所有有注解的api，用这种方式更灵活
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                // 扫描所有包中的swagger注解
                .paths(PathSelectors.any())
                .build()
                .securitySchemes(securitySchemes())
                .securityContexts(securityContexts());

    }

    /**
     * 添加摘要信息
     */
    public ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // 设置标题
                .title("标题：尹稳健管理系统_Swagger3接口文档")
                // 描述
                .description("尹稳健无敌第一帅~")
                .contact(new Contact("yinwenjian", null, null))
                // 作者信息
                .version("v1.0")
                // 版本
                .build();
    }

    /**
     * 安全模式，这里指定token通过Authorization头请求头传递
     * 通过 securitySchemes 来配置全局参数，这里的配置是一个名为 Authorization 的请求头（OAuth2 中需要携带的请求头）。
     */
    private List<SecurityScheme> securitySchemes() {
        List<SecurityScheme> apiKeyList = new ArrayList<SecurityScheme>();
        apiKeyList.add(new ApiKey("Authorization", "Authorization", In.HEADER.toValue()));
        return apiKeyList;
    }

    /**
     * 安全上下文
     * securityContexts 则用来配置有哪些请求需要携带 Token，这里我们配置了所有请求
     */
    private List<SecurityContext> securityContexts() {
        List<SecurityContext> securityContexts = new ArrayList<>();
        securityContexts.add(
                SecurityContext.builder()
                        .securityReferences(defaultAuth())
                        .operationSelector(o -> o.requestMappingPattern().matches("/.*"))
                        .build());
        return securityContexts;
    }

    /**
     * 默认的安全上引用
     */
    private List<SecurityReference> defaultAuth() {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        List<SecurityReference> securityReferences = new ArrayList<>();
        securityReferences.add(new SecurityReference("Authorization", authorizationScopes));
        return securityReferences;
    }
}

测试类接口：

package com.sky.controller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;

import javax.servlet.http.HttpServletRequest;

/**
 * @author 尹稳健~
 * @version 1.0
 * @time 2022/9/6
 */
@Api(tags = "测试接口类")
@RestController
@Slf4j
public class HelloController {

    @ApiOperation("测试hello")
    @PostMapping("/hello")
    public String hello(HttpServletRequest request){
        String authorization = request.getHeader("Authorization");
        log.info(authorization);
        return "hello";
    }
}

运行：

在这里插入图片描述

然后尝试调用controller接口

在这里插入图片描述

查看控制台打印

2022-09-06 14:56:55.147  INFO 21812 --- [nio-8080-exec-7] com.sky.controller.HelloController       : Bearer eyJhbGciOiJIUzI1NiJ9.eyJpZCI6MSwiaWF0IjoxNjYyMjc1MjM1LCJleHAiOjE2NjIyNzcwMzV9.VFMdI_VjKL0nHJOWcEeOR8b0sUCXdQoqfJD3uUP5VoU

能获取到token信息。这样swagger3的配置就全部完成了。谢谢能看到最后！

# spring boot
Logo
华为开发者空间

华为开发者空间，是为全球开发者打造的专属开发空间，汇聚了华为优质开发资源及工具，致力于让每一位开发者拥有一台云主机，基于华为根生态开发、创新。

更多推荐

cover

一文带你搞懂GaussDB数据库性能调优

avatar 华为开发者空间
cover

GaussDB全密态数据库等值查询

avatar 华为开发者空间
cover

GaussDB部署架构

avatar 华为开发者空间