【WEEK14】 【DAY4】Swagger Part 2【English Version】

2024.5.30 Thursday
Following up on 【WEEK14】 【DAY3】Swagger Part 1【English Version】

16.4. Configure Scanned Interfaces

Configuring scanned interfaces when building Docket using the select() method

16.4.1. Modify SwaggerConfig.java

16.4.1.1. Use the .basePackage() Method to Specify the Package Path for Scanning

package com.P47.config;import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;import java.util.ArrayList;@Configuration  // Equivalent to @Component
@EnableSwagger2 // Enable Swagger2
public class SwaggerConfig {// Configure the bean instance Docket for Swagger, to set specific parameters for Swagger@Beanpublic Docket docket(){return new Docket(DocumentationType.SWAGGER_2)  // See the source code in DocumentationType.class, select the appropriate version for editing.apiInfo(apiInfo()) // Public Docket(DocumentationType documentationType) method, click on ApiInfo to go to ApiInfo.class.select()   // Configure the scanning interface using the .select() method, RequestHandlerSelectors configures how to scan interfaces.apis(RequestHandlerSelectors.basePackage("com.P47.controll")).build();// Click into Docket.class to see the source code of various methods}// Configure Swagger information (apiInfo)private ApiInfo apiInfo(){// Prevent DEFAULT_CONTACT (name changed to contact) from reporting errorsContact contact = new Contact("Contact Name", "Contact URL", "Contact Email");return new ApiInfo("Swagger Api Documentation", // Title"Api Documentation Description", // Description"version 1.0",  // Version number"http://terms.service.url",  // Organization URLcontact,    // Contact information"Apache 2.0",   // License"http://www.apache.org/licenses/LICENSE-2.0",   // License URLnew ArrayList<>() // Extensions);}
}

After restarting, check: only the hello-controller section remains

16.4.1.2. Other Scanning Methods Can Be Found in the Source Code of RequestHandlerSelectors.class

basePackage(final String basePackage) // Scan interfaces based on package path
any() // Scan all, all interfaces in the project will be scanned
none() // Do not scan interfaceswithMethodAnnotation(final Class<? extends Annotation> annotation)  // Scan based on method annotation, e.g., withMethodAnnotation(GetMapping.class) only scans GET requests
withClassAnnotation(final Class<? extends Annotation> annotation)   // Scan based on class annotation, e.g., withClassAnnotation(Controller.class) only scans interfaces in classes annotated with @Controller

16.4.2. Continue to Modify SwaggerConfig.java

16.4.2.1. Configure Interface Scanning Filters

Add the following filter

.paths(PathSelectors.ant("/P47/**"))    // Click on path to see the initialization of private Predicate<String> pathSelector; Here, using the .ant() method as an example, only scan interfaces with requests starting with /P47

After restarting, check: no methods are displayed

16.4.2.2. Other Methods:

Here is the translated content while keeping the non-comment parts of the code unchanged:

At this time, the complete modified code

package com.P47.config;import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;import java.util.ArrayList;@Configuration  // Equivalent to @Component
@EnableSwagger2 // Enable Swagger2
public class SwaggerConfig {// Configure the bean instance Docket for Swagger, to set specific parameters for Swagger@Beanpublic Docket docket(){return new Docket(DocumentationType.SWAGGER_2)  // See the source code in DocumentationType.class, select the appropriate version for editing.apiInfo(apiInfo()) // Public Docket(DocumentationType documentationType) method, click on ApiInfo to go to ApiInfo.class.select()   // Configure the scanning interface using the .select() method, RequestHandlerSelectors configures how to scan interfaces.apis(RequestHandlerSelectors.basePackage("com.P47.controll"))  // Use basePackage to specify the package to scan.paths(PathSelectors.ant("/P47/**"))    // Click on path to see the initialization of private Predicate<String> pathSelector; Here, using the .ant() method as an example, only scan interfaces with requests starting with /P47.build();// Click into Docket.class to see the source code of various methods/*RequestHandlerSelectors. MethodsbasePackage(final String basePackage) // Scan interfaces based on package pathany() // Scan all, all interfaces in the project will be scannednone() // Do not scan interfaceswithMethodAnnotation(final Class<? extends Annotation> annotation)  // Scan based on method annotation, e.g., withMethodAnnotation(GetMapping.class) only scans GET requestswithClassAnnotation(final Class<? extends Annotation> annotation)   // Scan based on class annotation, e.g., withClassAnnotation(Controller.class) only scans interfaces in classes annotated with @Controller*//*PathSelectors. Methodsany() // Scan any requestnone() // Do not scan any requestregex(final String pathRegex) // Control through regular expressionsant(final String antPattern) // Control through ant()*/}// Configure Swagger information (apiInfo)private ApiInfo apiInfo(){// Prevent DEFAULT_CONTACT (name changed to contact) from reporting errorsContact contact = new Contact("Contact Name", "Contact URL", "Contact Email");return new ApiInfo("Swagger Api Documentation", // Title"Api Documentation Description", // Description"version 1.0",  // Version number"http://terms.service.url",  // Organization URLcontact,    // Contact information"Apache 2.0",   // License"http://www.apache.org/licenses/LICENSE-2.0",   // License URLnew ArrayList<>() // Extensions);}
}

16.5. Configure Swagger Switch

Modify SwaggerConfig.java

16.5.1. Modify the Value of enable to Disable Swagger

@Bean
public Docket docket(){return new Docket(DocumentationType.SWAGGER_2)  // See the source code in DocumentationType.class, select the appropriate version for editing.apiInfo(apiInfo()) // Public Docket(DocumentationType documentationType) method, click on ApiInfo to go to ApiInfo.class.enable(false)  // Whether to enable Swagger, if false it cannot be started, and the page shows: 😱 Could not render e, see the console..select()   // Configure the scanning interface using the .select() method, RequestHandlerSelectors configures how to scan interfaces//.apis(RequestHandlerSelectors.basePackage("com.P47.controll"))  // Use basePackage to specify the package to scan//.paths(PathSelectors.ant("/P47/**"))    // Click on path to see the initialization of private Predicate<String> pathSelector; Here, using the .ant() method as an example, only scan interfaces with requests starting with /P47.build();}

Restart:

16.5.2. Dynamically Configure Swagger to Display in Test and Dev Environments, but Not in Prod

16.5.2.1. Modify SwaggerConfig

@Bean
public Docket docket(Environment environment){// Set the environments where Swagger should be displayedProfiles profiles = Profiles.of("dev", "test");// Determine if the current environment matches the profiles// Use enable() to accept this parameter and decide whether to display Swaggerboolean flag = environment.acceptsProfiles(profiles);return new Docket(DocumentationType.SWAGGER_2)  // See the source code in DocumentationType.class, select the appropriate version for editing.apiInfo(apiInfo()) // Public Docket(DocumentationType documentationType) method, click on ApiInfo to go to ApiInfo.class.enable(flag)  // Whether to enable Swagger, if false it cannot be started, and the page shows: 😱 Could not render e, see the console..select()   // Configure the scanning interface using the .select() method, RequestHandlerSelectors configures how to scan interfaces//.apis(RequestHandlerSelectors.basePackage("com.P47.controll"))  // Use basePackage to specify the package to scan//.paths(PathSelectors.ant("/P47/**"))    // Click on path to see the initialization of private Predicate<String> pathSelector; Here, using the .ant() method as an example, only scan interfaces with requests starting with /P47.build();}

At this time, the complete code:

package com.P47.config;import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;import java.util.ArrayList;@Configuration  // Equivalent to @Component
@EnableSwagger2 // Enable Swagger2
public class SwaggerConfig {// Configure the bean instance Docket for Swagger, to set specific parameters for Swagger@Beanpublic Docket docket(Environment environment){// Set the environments where Swagger should be displayedProfiles profiles = Profiles.of("dev", "test");// Determine if the current environment matches the profiles// Use enable() to accept this parameter and decide whether to display Swaggerboolean flag = environment.acceptsProfiles(profiles);return new Docket(DocumentationType.SWAGGER_2)  // See the source code in DocumentationType.class, select the appropriate version for editing.apiInfo(apiInfo()) // Public Docket(DocumentationType documentationType) method, click on ApiInfo to go to ApiInfo.class.enable(flag)  // Whether to enable Swagger, if false it cannot be started, and the page shows: 😱 Could not render e, see the console..select()   // Configure the scanning interface using the .select() method, RequestHandlerSelectors configures how to scan interfaces//.apis(RequestHandlerSelectors.basePackage("com.P47.controll"))  // Use basePackage to specify the package to scan//.paths(PathSelectors.ant("/P47/**"))    // Click on path to see the initialization of private Predicate<String> pathSelector; Here, using the .ant() method as an example, only scan interfaces with requests starting with /P47.build();}// Configure Swagger information (apiInfo)private ApiInfo apiInfo(){// Prevent DEFAULT_CONTACT (name changed to contact) from reporting errorsContact contact = new Contact("Contact Name", "Contact URL", "Contact Email");return new ApiInfo("Swagger Api Documentation", // Title"Api Documentation Description", // Description"version 1.0",  // Version number"http://terms.service.url",  // Organization URLcontact,    // Contact information"Apache 2.0",   // License"http://www.apache.org/licenses/LICENSE-2.0",   // License URLnew ArrayList<>() // Extensions);}
}

16.5.2.2. Modify application.properties

spring.application.name=swagger-demo
spring.mvc.pathmatch.matching-strategy=ant_path_matcher
spring.profiles.active=dev

16.5.2.3. Create application-dev.properties

# Production environment
server.port=8081

16.5.2.4. Create application-pro.properties

# Test environment
server.port=8082

16.5.2.5. Restart

Access http://localhost:8081/swagger-ui.html

Change the configuration in application.properties to spring.profiles.active=pro, and access http://localhost:8082/swagger-ui.html to find that the Swagger page cannot be accessed.

Similarly, if you do not specify a profile in spring.profiles.active, the default port is 8080. Due to the configuration in SwaggerConfig, http://localhost:8080/swagger-ui.html cannot access Swagger either.