// 定义包路径，用于存放Swagger配置类相关的代码。这个包名表明该类属于特定的项目模块（com.yf.exam）下的config部分， // 通常用于组织和管理与Swagger配置相关的代码。 package com.yf.exam.config; // 导入用于启用Swagger Bootstrap UI的注解，Swagger Bootstrap UI是对Swagger UI的一种增强， // 提供了更友好的界面展示和交互功能，通过该注解可以在项目中启用这一特性。 import com.github.xiaoymin.swaggerbootstrapui.annotations.EnableSwaggerBootstrapUI; // 导入Swagger用于标注API操作的注解，通过在方法上添加该注解，可以为该方法在Swagger文档中生成详细的操作描述信息， // 包括方法的功能、参数、返回值等内容，方便开发者和使用者了解API的具体使用方式。 import io.swagger.annotations.ApiOperation; // 导入Spring框架中用于将类的属性与配置文件中的属性进行绑定的注解。 // 通过指定prefix属性，可以将配置文件中以该前缀开头的属性值绑定到类的对应属性上， // 在本类中用于绑定以"swagger"为前缀的配置属性。 import org.springframework.boot.context.properties.ConfigurationProperties; // 导入Spring框架中用于标记一个方法返回值为Spring Bean的注解。 // 被该注解标记的方法，其返回值会被Spring容器管理，作为一个可被注入到其他组件中的Bean实例。 // 在本类中用于将examApi、securityScheme等方法返回的对象注册为Spring Bean。 import org.springframework.context.annotation.Bean; // 导入Spring框架中用于标记一个类是配置类的注解。 // 被该注解标记的类可以在其中定义各种Bean配置方法，这些方法会被Spring容器在启动时自动识别并执行， // 用于创建和配置应用程序所需的各种组件。在本类中用于标记该类为Spring配置类，以便进行Swagger相关的配置。 import org.springframework.context.annotation.Configuration; // 导入Swagger用于构建API信息的构建器类，通过该构建器可以方便地设置API的标题、描述、联系人、版本等信息， // 在本类的apiInfo方法中用于创建并返回包含详细API信息的ApiInfo对象。 import springfox.documentation.builders.ApiInfoBuilder; // 导入Swagger用于选择路径的选择器类，通过该选择器可以指定哪些路径下的API需要被Swagger生成文档并展示， // 在本类的examApi方法中用于选择符合特定路径模式的API。 import springfox.documentation.builders.PathSelectors; // 导入Swagger用于选择请求处理器（即包含API方法的类或接口）的选择器类， // 通过该选择器可以指定哪些请求处理器中的方法需要被Swagger生成文档并展示， // 在本类的examApi方法中用于选择带有ApiOperation注解的方法所在的请求处理器。 import springfox.documentation.builders.RequestHandlerSelectors; // 导入Swagger用于表示API信息的类，该类包含了API的标题、描述、联系人、版本等详细信息， // 在本类的examApi方法中通过调用apiInfo方法获取该对象并设置到Docket中，以便在Swagger文档中展示这些信息。 import springfox.documentation.service.ApiInfo; // 导入Swagger用于表示API密钥的类，用于设置API的授权相关信息，如授权的键名、值的位置（如在请求头中）等， // 在本类的securityScheme方法中用于创建并返回一个ApiKey对象，用于设置API的授权方案。 import springfox.documentation.service.ApiKey; // 导入Swagger用于表示联系人信息的类，通过该类可以设置API的联系人姓名、联系方式、网址等信息， // 在本类的apiInfo方法中用于创建并返回一个包含联系人信息的Contact对象，并设置到ApiInfo中。 import springfox.documentation.service.Contact; // 导入Swagger用于表示安全方案的类，它是一个通用的接口，用于定义不同类型的安全方案， // 在本类的examApi方法中通过调用securityScheme方法获取具体的安全方案实现（如ApiKey）并设置到Docket中。 import springfox.documentation.service.SecurityScheme; // 导入Swagger用于表示文档类型的枚举类，目前主要有SWAGGER_2等类型， // 在本类的examApi方法中用于指定创建Docket对象时所采用的文档类型为SWAGagger_2。 import springfox.documentation.spi.DocumentationType; // 导入Swagger用于生成Swagger文档的核心类，通过该类可以配置各种Swagger相关的设置，如API信息、路径选择、 // 授权方案等，在本类的examApi方法中用于创建并配置Docket对象，以生成符合项目需求的Swagger文档。 import springfox.documentation.spring.web.plugins.Docket; // 导入用于启用Swagger 2的注解，通过在类上添加该注解，可以在项目中启用Swagger 2的功能， // 使得Swagger能够为项目中的API生成详细的文档并提供交互界面，方便开发者和使用者查看和测试API。 import springfox.documentation.swagger2.annotations.EnableSwagger2; // 导入Java标准库中的集合类，用于处理集合相关的操作，在本类的examApi方法中用于创建一个包含单个安全方案的列表， // 以便将安全方案设置到Docket对象中。 import java.util.Collections; /** * Swagger配置类，主要功能是配置Swagger在项目中的相关设置， * 包括启用Swagger 2和Swagger Bootstrap UI功能，绑定以"swagger"为前缀的配置属性， * 创建Docket对象并设置其API信息、分组名称、选择需要生成文档的API方法和路径、设置安全方案等， * 以生成详细的API文档并提供友好的交互界面，方便对项目中的API进行查看、测试和使用。 * @author bool * @date 2020/8/19 20:53 */ @Configuration // 使用该注解标记此为Spring配置类，表明这个类是用来进行Spring应用程序的配置工作的。 @EnableSwagger2 // 使用该注解启用Swagger 2功能，使得Swagger能够为项目中的API生成详细的文档并提供交互界面。 @EnableSwaggerBootstrapUI // 使用该注解启用Swagger Bootstrap UI功能，提供更友好的界面展示和交互功能。 @ConfigurationProperties(prefix = "swagger") // 使用该注解将类的属性与以"swagger"为前缀的配置文件中的属性进行绑定， // 以便在类中可以方便地使用这些配置属性来定制Swagger的设置。 public class SwaggerConfig { /** * 定义一个方法，并使用@Bean注解将其返回值声明为Spring Bean。 * 该方法用于创建并返回一个Docket对象，该对象是Swagger生成文档的核心组件， * 通过对其进行一系列设置，可以定制生成的API文档的内容和展示方式。 * * @return 返回一个Docket对象，该对象经过了相关设置，包括API信息、分组名称、选择的API方法和路径、安全方案等。 */ @Bean // 将该方法返回的Docket对象声明为Spring Bean，以便Spring容器能够管理和注入到其他需要使用的地方。 public Docket examApi() { return new Docket(DocumentationType.SWAGGER_2) // 创建一个新的Docket对象，并指定文档类型为SWAGGER_2， // 这是目前较为常用的Swagger文档类型，用于生成详细的API文档。 .apiInfo(apiInfo()) // 调用apiInfo方法获取包含详细API信息的ApiInfo对象，并设置到Docket对象中， // 以便在生成的Swagger文档中展示API的标题、描述、联系人、版本等信息。 .groupName("考试模块接口") // 设置Docket对象的分组名称为"考试模块接口"， // 这样可以将项目中的API按照不同的模块或功能进行分组展示，方便查看和管理。 .select() // 开始选择需要生成文档的API，通过一系列选择器来指定具体的选择条件。 .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) // 使用RequestHandlerSelectors的withMethodAnnotation方法选择带有ApiOperation注解的方法， // 即只选择那些在方法上标注了ApiOperation注解的API方法进行文档生成， // 这样可以确保只生成我们希望展示的重要API的文档。 .paths(PathSelectors.ant("/exam/api/**")) // 使用PathSelectors的ant方法选择符合特定路径模式的API， // 这里选择的路径模式是"/exam/api/**"，表示只选择以"/exam/api/"开头的任意路径下的API进行文档生成， // 进一步限定了生成文档的API范围，使其更加聚焦于项目中的特定部分（如考试模块相关的API）。 .build() // 完成上述选择条件的设置后，调用build方法构建Docket对象，使其生效并包含我们所设置的所有选择条件和信息。 .securitySchemes(Collections.singletonList(securityScheme())) // 创建一个包含单个安全方案的列表， // 通过调用securityScheme方法获取具体的安全方案对象（如ApiKey）， // 并将其添加到列表中，然后设置到Docket对象中， // 以便在Swagger文档中展示API的授权相关信息，如需要在请求头中传递的授权密钥等。 ; } /** * 用于创建并返回一个包含详细API信息的ApiInfo对象的方法。 * 通过ApiInfoBuilder类可以方便地设置API的标题、描述、联系人、版本等信息。 * * @return 返回一个ApiInfo对象，该对象包含了API的标题、描述、联系人、版本等详细信息， * 用于设置到Docket对象中，以便在Swagger文档中展示。 */ private ApiInfo apiInfo() { return new ApiInfoBuilder().title("考试系统接口") // 使用ApiInfoBuilder的title方法设置API的标题为"考试系统接口"， // 这将在Swagger文档的顶部显著位置展示，让使用者快速了解该API所属的系统。 .description("考试系统接口") // 使用ApiInfoBuilder的description方法设置API的描述为"考试系统接口"， // 可以在这里详细描述API的功能、用途、特点等信息，方便使用者进一步了解API的具体情况。 .contact(new Contact("Van", "https://exam.yfhl.net", "18365918@qq.com")) // 使用ApiInfoBuilder的contact方法创建一个包含联系人信息的Contact对象， // 并设置联系人姓名为"Van"，网址为"https://exam.yfhl.net"，邮箱为"18365918@qq.com"， // 这些信息将在Swagger文档中展示，方便使用者在有问题时能够联系到相关人员。 .version("1.0.0") // 使用ApiInfoBuilder的version方法设置API的版本号为"1.0.0"， // 让使用者了解该API的版本情况，以便在不同版本之间进行对比和选择。 .build(); // 完成上述各项信息的设置后，调用build方法构建ApiInfo对象，使其生效并包含我们所设置的所有信息。 } /** * 用于创建并返回一个表示API密钥的ApiKey对象的方法，该对象用于设置API的授权方案。 * * @return 返回一个ApiKey对象，该对象定义了API的授权相关信息，如授权的键名、值的位置（如在请求头中）等， * 用于设置到Docket对象中，以便在Swagger文档中展示API的授权要求。 */ @Bean // 将该方法返回的SecurityScheme对象（实际为ApiKey类型）声明为Spring Bean，以便Spring容器能够管理和注入到其他需要使用的地方。 SecurityScheme securityScheme() { return new ApiKey("token", "token", "header"); // 创建一个新的ApiKey对象， // 第一个参数"token"表示授权的键名，即客户端在请求时需要在指定位置（这里是请求头）传递的键名； // 第二个参数"token"表示授权的值，这里简单设置为与键名相同，实际应用中可能是根据用户登录等情况生成的授权令牌； // 第三个参数"header"表示授权的值应该放置的位置，这里指定为在请求头中传递。 } }