一、导入依赖

由于原生的 Swagger 界面实在太丑，所以直接使用[knife4j](https://xiaoym.gitee.io/knife4j/),其官网为：https://xiaoym.gitee.io/knife4j/documentation/get_start.html

注入依赖：

  1. <dependency>
  2.         <groupId>com.github.xiaoymin</groupId>
  3.         <artifactId>knife4j-spring-boot-starter</artifactId>
  4.         <version>2.0.9</version>
  5. </dependency>

二、配置 Swagger

  1. @Configuration
  2. @EnableSwagger2WebMvc
  3. public class Knife4jConfiguration {
  5.     @Bean(value = "defaultApi2")
  6.     public Docket defaultApi2() {
  7.         Docket docket=new Docket(DocumentationType.SWAGGER_2)
  8.             .apiInfo(new ApiInfoBuilder()
  9.                      //.title("swagger-bootstrap-ui-demo RESTful APIs")
  10.                      .description("# swagger-bootstrap-ui-demo RESTful APIs")
  11.                      .termsOfServiceUrl("http://www.xx.com/")
  12.                      .contact("xx@qq.com")
  13.                      .version("1.0")
  14.                      .build())
  15.             //分组名称
  16.             .groupName("2.X版本")
  17.             .select()
  18.             //这里指定Controller扫描包路径
  19.             .apis(RequestHandlerSelectors.basePackage("com.github.xiaoymin.knife4j.controller"))
  20.             .paths(PathSelectors.any())
  21.             .build();
  22.         return docket;
  23.     }
  24. }

三、高版本依赖报错

导入依赖运行项目出现下面错误信息：

  1. Failed to start bean 'documentationPluginsBootstrapper'; 
  2. nested exception is java.lang.NullPointerException

这是因为Spring Boot2.6.0+以上的版本是默认禁止 Bean 的循环引用。

  • 解决办法1：就是降低SpringBoot的版本；
  • 解决办法2：添加如下配置：
    1. spring:
    2. mvc:
    3.   pathmatch:
    4.     matching-strategy: ANT_PATH_MATCHER

四、JWT配置

  1. import io.swagger.annotations.ApiOperation;
  2. import org.springframework.context.annotation.Bean;
  3. import org.springframework.context.annotation.Configuration;
  4. import springfox.documentation.builders.ApiInfoBuilder;
  5. import springfox.documentation.builders.PathSelectors;
  6. import springfox.documentation.builders.RequestHandlerSelectors;
  7. import springfox.documentation.service.*;
  8. import springfox.documentation.spi.DocumentationType;
  9. import springfox.documentation.spi.service.contexts.SecurityContext;
  10. import springfox.documentation.spring.web.plugins.ApiSelectorBuilder;
  11. import springfox.documentation.spring.web.plugins.Docket;
  12. import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;
  14. import java.util.ArrayList;
  15. import java.util.List;
  17. @Configuration // 声明配置类
  18. @EnableSwagger2WebMvc
  19. public class SwaggerConfig2 {
  20.     @Bean
  21.     public Docket create() {
  22.         Docket docket = new Docket(DocumentationType.SWAGGER_2);
  24.         /** 1.设置Swagger的基本信息 */
  25.         // ApiInfoBuilder 用于在Swagger界面上添加各种信息
  26.         ApiInfoBuilder apiInfoBuilder = new ApiInfoBuilder();
  27.         // 添加标题
  28.         apiInfoBuilder.title("EMOS在线办公系统");
  29.         // 将基本信息封装到 ApiInfo 类中并添加到 docket
  30.         ApiInfo apiInfo = apiInfoBuilder.build();
  31.         docket.apiInfo(apiInfo);
  33.         /** 2.设置哪些类的哪些方法添加到Swagger中 */
  34.         // ApiSelectorBuilder 用来设置哪些类中的方法会生成到REST API中
  35.         ApiSelectorBuilder apiSelectorBuilder = docket.select();
  36.         // 设置所有的类都可以被添加到swagger中
  37.         apiSelectorBuilder.paths(PathSelectors.any()); // PathSelectors.any() 表示包下的所有类
  38.         // 设置只有方法上包含ApiOperation注解的方法才能被添加到Swagger中
  39.         // 使用@ApiOperation的方法会被提取到REST API中
  40.         apiSelectorBuilder.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class));
  41.         docket = apiSelectorBuilder.build();
  43.         /** 3.设置JWT单点登录功能
  44.          *  下面的语句是开启对JWT的支持，当用户用Swagger调用受JWT认证保护的方法时，
  45.          *  必须要先提交参数（例如令牌）
  46.          * */
  47.         // 规定在header(3)中接收令牌，请求头中的参数为token(1)，描述信息为token(2)
  48.         // 存储用户必须提交的参数
  49.         ApiKey apiKey = new ApiKey("token", "token", "header");
  50.         List<SecurityScheme> securitySchemeList = new ArrayList<>();
  51.         // 规定用户需要输入什么参数
  52.         securitySchemeList.add(apiKey);
  53.         // swagger就知道了在请求头里面的token参数提交的令牌字符串
  54.         docket.securitySchemes(securitySchemeList);
  56.         // 如果Swagger判断的令牌有效，则设置令牌的作用域
  57.         // 这里设置作用域为全局
  58.         // 如果用户JWT认证通过，则在Swagger中全局有效
  59.         AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
  60.         AuthorizationScope[] scopes = {authorizationScope};
  61.         // 存储令牌和作用域
  62.         SecurityReference reference = new SecurityReference("token", scopes);
  63.         List<SecurityReference> referenceList = new ArrayList<>();
  64.         referenceList.add(reference);
  65.         SecurityContext context = SecurityContext.builder().securityReferences(referenceList).build();
  66.         List<SecurityContext> contextList = new ArrayList<>();
  67.         contextList.add(context);
  68.         docket.securityContexts(contextList);
  69.         return docket;
  70.     }
  71. }