|
|
// 定义包路径，用于存放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"表示授权的值应该放置的位置，这里指定为在请求头中传递。
|
|
|
}
|
|
|
} |
