第三章🚦API文档-Swagger配置🌼基于SpringBoot+Vue前后端分离的Java快速开发框架 🌼API

🧑‍🎓 个人主页：花棉袄

📖 本章内容：【SpringBoot-Swagger配置】

🌼API文档-Swagger配置👉 Gitee仓库地址

🍵Swagger介绍

🌳多一句没有-少一句不行
🌳Swagger 是一个规范和完整的框架
🌳用于生成、描述、调用和可视化 RESTful 风格的Web 服务
🌳总体目标是使客户端和文件系统作为服务器以同样的速度来更新
🌳swagger可以自动生成在线文档，界面可视化的同时保证了便利的测试接口

🍣引入依赖

<!--swagger3-->
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-boot-starter</artifactId>
   <version>3.0.0</version>
</dependency>

🥗配置信息

# 开发环境配置
server:
  # 服务器的HTTP端口，默认为8080
  port: 8080
  servlet:
    # 应用的访问路径
    context-path: /dev-api

# Swagger配置
swagger:
  # 是否开启swagger
  enabled: true
  # 请求前缀
  pathMapping: /dev-api

# 项目配置
michale:
  # 名称
  name: Michale
  # 版本
  version: 1.0.1
  # 版权年份
  copyrightYear: 2022
  # 文件路径 示例（ Windows配置D:/Michale/uploadPath，Linux配置 /home/Michale/uploadPath）
  profile: E:/Michale/uploadPath
  # 获取ip地址开关
  addressEnabled: false
  # 验证码类型 math 数组计算 char 字符验证
  captchaType: math

🫒读取配置信息类

/**
 * Author: 花棉袄
 * CreateDate: 2022年08月22日
 * Describe: 账户信息配置
 */
@Data
@Component
@ConfigurationProperties(prefix = "michale")
public class MichaleProperties {

    @ApiModelProperty("项目名称")
    private String name;

    @ApiModelProperty("版本")
    private String version;

    @ApiModelProperty("实例演示开关")
    private boolean demoEnabled;

    @ApiModelProperty("版权年份")
    private String copyrightYear;

    @ApiModelProperty("上传路径")
    private static String profile;

    @ApiModelProperty("获取地址开关")
    private static boolean addressEnabled;

    @ApiModelProperty("验证码类型")
    private static String captchaType;


    @ApiModelProperty("获取导入上传路径")
    public static String getImportPath() {
        return getProfile() + "/import";
    }

    @ApiModelProperty("获取头像上传路径")
    public static String getAvatarPath() {
        return getProfile() + "/avatar";
    }

    @ApiModelProperty("获取下载路径")
    public static String getDownloadPath() {
        return getProfile() + "/download/";
    }

    @ApiModelProperty("获取上传路径")
    public static String getUploadPath() {
        return getProfile() + "/upload";
    }
}

@Data
@Component
@ConfigurationProperties(prefix = "swagger")
public class SwaggerProperties {

    @ApiModelProperty("是否开启swagger")
    private String enabled;

    @ApiModelProperty("请求前缀")
    private String pathMapping;

    @ApiModelProperty("标题")
    private String title;

    @ApiModelProperty("描述")
    private String description;

    @ApiModelProperty("网址")
    private String url;

    @ApiModelProperty("邮箱")
    private String email;
}

🍏Swagger配置类

/**
 * @Author: 花棉袄
 * @CreateDate: 2022年08月23日
 * @Describe: Swagger2API文档的配置
 */
@Configuration
@EnableOpenApi
@EnableSwagger2
public class Swagger2Config {
    @Autowired
    private MichaleProperties michaleProperties;
    @Autowired
    private SwaggerProperties swaggerProperties;

    @Bean
    public Docket restApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(Boolean.parseBoolean(swaggerProperties.getEnabled()))
                .groupName(michaleProperties.getName())
                .apiInfo(apiInfo())
                .useDefaultResponseMessages(true)
                .forCodeGeneration(false)
                .select()
                //.apis(RequestHandlerSelectors.basePackage("com.michale"))
                .paths(PathSelectors.any())
                .build()
                /* 设置安全模式，swagger可以设置访问token */
                .securitySchemes(securitySchemes())
                .securityContexts(securityContexts())
                ;
    }

    /**
     * 安全模式，这里指定token通过Authorization头请求头传递
     */
    private List<SecurityScheme> securitySchemes() {
        List<SecurityScheme> apiKeyList = new ArrayList<SecurityScheme>();
        apiKeyList.add(new ApiKey("Authorization", "Authorization", In.HEADER.toValue()));
        return apiKeyList;
    }

    /**
     * 安全上下文
     */
    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;
    }

    /**
     * 创建该API的基本信息（这些基本信息会展现在文档页面中）
     *
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title(swaggerProperties.getTitle())
                .description(swaggerProperties.getDescription())
                .contact(new Contact(michaleProperties.getName(), swaggerProperties.getUrl(), swaggerProperties.getEmail()))
                .version("版本" + michaleProperties.getVersion())
                .build();
    }
}

🍎设置拦截规则

/**
 * @Author: 花棉袄
 * @CreateDate: 2022年09月01日
 * @Describe: 配置拦截规则
 */
@Configuration
public class SwaggerMebMvcConfig implements WebMvcConfigurer {

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        /** 本地文件上传路径 */
        registry.addResourceHandler(CommonConstant.RESOURCE_PREFIX + "/**")
                .addResourceLocations("file:" + MichaleProperties.getProfile() + "/");

        /** swagger配置 */
        registry.addResourceHandler("/swagger-ui/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/springfox-swagger-ui/");
    }

    /**
     * 跨域配置
     */
    @Bean
    public CorsFilter corsFilter() {
        CorsConfiguration config = new CorsConfiguration();
        config.setAllowCredentials(true);
        // 设置访问源地址
        config.addAllowedOriginPattern("*");
        // 设置访问源请求头
        config.addAllowedHeader("*");
        // 设置访问源请求方法
        config.addAllowedMethod("*");
        // 有效期 1800秒
        config.setMaxAge(1800L);
        // 添加映射路径，拦截一切请求
        UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
        source.registerCorsConfiguration("/**", config);
        // 返回新的CorsFilter
        return new CorsFilter(source);
    }
}

🚀访问地址：http://localhost:8080/swagger-ui/index.html

🍑API详细说明

在这里插入图片描述

更多介绍请移步：👉🏽官网地址

🕰️整合knife4j

Knife4j是一个集Swagger2 和 OpenAPI3 为一体的增强解决方案
knife4j：👉🏽官网地址

knife4j：快速开始

第一步：创建Spring Boot项目并且在pom.xml中引入Knife4j的依赖包

<!--引入Knife4j的官方start包,Swagger2基于Springfox2.10.5项目-->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <!--使用Swagger2-->
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>2.0.9</version>
</dependency>

@Api(tags = "首页模块")
@RestController
public class IndexController {

    @ApiImplicitParam(name = "name",value = "姓名",required = true)
    @ApiOperation(value = "向客人问好")
    @GetMapping("/sayHi")
    public ResponseEntity<String> sayHi(@RequestParam(value ="name")Stringname){
    return ResponseEntity.ok("Hi:"+name);
    }
}

如果开发者使用的是Knife4j 2.x版本，并且Spring Boot版本高于2.4
那么需要在Spring Boot的yml文件中做如下配置

spring:
  mvc:
    pathmatch:
      # 配置策略
      matching-strategy: ant-path-matcher

启动Spring Boot项目，浏览器访问Knife4j的文档地址即可查看效果
🚀访问地址：http://localhost:8080/doc.html

扫码_搜索联合传播样式-标准色版.png

📢💨如果文章对你有帮助【关注👍点赞❤️收藏⭐】