SpringBoot 2.3 Upgrade to SpringBoot 2.7 Pit Crawl - SpringDoc & Swagger

Note: Swagger supports SpringBoot 2.0 but not SpringBoot 3.0.
OpenApi
OpenApi is a specification for describing, defining, and sharing RESTful API documents. The latest specification is OpenAPI 3.0

Swagger
Swagger is a tool for designing and testing RESTful APIs.
It provides API description , request and response examples , API testing and documentation generation and other rich features . The latest version is Swagger3, which supports the OpenAPI 3.0 specification.

SpringFox
SpringFox is a (unofficial) project maintained by the Spring community to help users integrate Swagger 2 into Spring.

SpringDoc
SpringDoc is also a (unofficial) project maintained by the Spring community to help users integrate Swagger 3 into Spring.

OpenAPI defines a standard format for representing API documentation, and Swagger is a tool that implements the OpenAPI specification.

SpringFox and SpringDoc are unofficial projects maintained by the Spring community to help developers integrate Swagger 2 and Swagger 3 into Spring, respectively.SpringFox hasn't been updated in a long time, so SpringDoc is definitely a better choice.

POM

<>1.6.9</>

<! --This package, which includes swagger-annotations, webmvc-core, etc.-->
<dependency>
    <groupId> </groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>${}</version>
</dependency>
<! --swagger is in an intranet development environment, so the security aspects are left out for now --> </version> </dependency>!
</dependency> <!
    <groupId> </groupId>
    <artifactId>springdoc-openapi-security</artifactId>
    <version>${}</version>
</dependency>

yml

As long as dev and test are configured in the intranet environment, it's best to add authorization if you're open to external testing.

# Docs API Configuration
springdoc.
  swagger-ui.
    # API documentation, default path: swagger-ui/, via http://localhost:8080/docs/interviews
    path: /docs/
    # Enable the Swagger UI
    enabled: true
    # Sort API paths by HTTP methods
    operations-sorter: method
  api-docs.
    # OpenAPI path description, default path:/v3/api-docs, via http://localhost:8080/docs/apiinterviews文档描述
    # OpenAPI description definition in JSON format by default, via http://localhost:8080/docs/gainyamlspecification
    path: /docs/api
    # Enable api-docs
    enabled: true
  # Configure the path to scan packages for generating interface documentation
  packages-to-scan.
  # Configure the interface paths for generating interface documentation
  # paths-to-match: /test/**,/user/**

Configuring a Customized OpenAPI Specification

OpenApiConfig

package ;

import . package ; import .
import . package ; import .
import . import .
import . import .
import . import .
import ;
import ;
import ;

@Configuration
public class OpenApiConfig {
    /**
     * Configure a custom OpenAPI specification.
     * Declare this method with the @Bean annotation to return a Spring bean that is an OpenAPI object.
     * This method allows you to initialize the OpenAPI object with a Spring Context and customize the title, version, description, etc. of the API.
     * @return
     * @return The customized OpenAPI object.
     */
    @Bean
    public OpenAPI customOpenAPI() {
        // Create and configure the OpenAPI object
        return new OpenAPI()
                .info(new Info())
                        .title("VipSoft API") // Set the API title.
                        .version("v2.0.1") // Set the API version.
                        .description("Backend Interface Service") // Set the API description.
                        .license(new License().name("Apache 2.0").url("")) // Set the license information for the API, including the license name and URL
                        .contact(new Contact())
                                .name("Jimmy") // Set the name of the contact
                                .url("") // Set the URL of the contact
                                .email("47262947@")) // Set the contact's email address.
                .externalDocs(new ExternalDocumentation()) // Set the contact's e-mail address.
                        .description("Description of the external document") // Set the description of the external document
                        .url("")); // set the URL of the external document
    }

    /**
     * Configures and returns a GroupedOpenApi instance to specify a set of API interfaces
     *
     * @return GroupedOpenApi instance configured with a group name of "test" matching the path "/test/**".
     */
    @Bean
    public GroupedOpenApi testApi() {
        return ()
                .group("menu") // set the group name
                .pathsToMatch("/menu/**") // set the path pattern to be matched
                .build();
    }
}

It can also be grouped in the configuration

# Docs APIconfigure
springdoc:
  swagger-ui:
    path: /docs/
    enabled: true
  group-configs:
    - group: 'beta (software)1'
      paths-to-match: /test/**
    - group: 'beta (software)2'
      paths-to-match: /test/**

Interceptor removes swagger's interface validation

WebConfig

package ;

import ;
import ;
import ;
import ;
import ;
import ;
import ;
import ;
import ;
import ;


@Configuration
public class WebConfig implements WebMvcConfigurer {

    @Autowired
    private AuthInterceptor authorizationInterceptor;

    /**
     * Adding Interceptors
     */
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        //Intercept paths can be self-configured with multiple usability ，separate
        InterceptorRegistration registration= (authorizationInterceptor);
        ("/**");
        (
                "/",
                "/swagger-resources/**",
                "/docs/**",
                "/error",
                "/webjars/**"
        );
    }

    /**
     * Cross-Domain Configuration
     */
    @Bean
    public CorsFilter corsFilter()
    {
        CorsConfiguration config = new CorsConfiguration();
        (true);
        // Setting the access source address
        ("*");
        // Setting the access source request header
        ("*");
        // Setting up the access source request method
        ("*");
        // validity period 1800unit of angle or arc equivalent one sixtieth of a degree
        (1800L);
        // Adding a mapping path，Intercept all requests
        UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
        ("/**", config);
        // Returns the newCorsFilter
        return new CorsFilter(source);
    }
}

mould

/**
 * Menu Permissions Table sys_menu
 */
@TableName("sys_menu")
@Schema(description = "Menu Information")
public class SysMenu extends BaseEntity
{
    private static final long serialVersionUID = 1L;

    /** menuID */
    @Schema(description = "menuID", example = "")
    private Long menuId;

    /** menu名称 */
    @Schema(description = "menu名称", example = "user management")
    @TableField("menu_name")
    private String menuName;
}

Controller Configuration

package ;

import ;
import ;
import ;
import ;
import ;
import .;
import .;
import .;
import .;
import .;
import ;
import ;
import ;
import ;

import ;

/**
 * Menu Information
 *
 */
@Tag(name = "beta (software)APIconnector", description = "这是一个关于beta (software)APIconnector的描述")
@RestController
@RequestMapping("/menu")
public class SysMenuController {
    @Autowired
    private ISysMenuService menuService;

    /**
     * Get menu list
     */
    @Operation(summary = "Get menu list", description = "pass (a bill or inspection etc) MyBatisPlus gain",method = "GET")
    @ApiResponse(responseCode = "1", description = "successes",content = @Content(mediaType = "application/json", schema = @Schema(implementation = )))
    @ApiResponse(responseCode = "-1", description = "gain失败")
    @GetMapping("/selectPage")
    @AuthIgnore
    public ApiResult selectPage(SysMenu menu) {
        IPage menus = (menu);
        return new ApiResult(menus);
    }
}

Commonly used annotations

explanatory note	descriptive
@Tag	Add tags to a set of API operations for easy organization and grouping in documentation.
@Operation	Describes an API operation, including a summary and detailed description.
@Parameter	Describes the method parameters, including the path variable, request body, and query parameters.
@Schema	Describes the attributes and structure of the data model, typically used as parameters and return values for model classes or API methods.
@ApiResponse	Describes the details of a single HTTP response status code.
@ApiResponses	Details describing multiple HTTP response status codes.
@RequestBody	Specifies the content type and structure of the request body.
@Content	Describes the type and format of the response content.
@SecurityRequirement	Describe the security requirements needed for API operations, such as authentication and authorization.
@Hidden	Specifies that an API operation or model is hidden from the document.
@Deprecated	Indicates that an API operation or model has been deprecated.
@ArraySchema	Describes the contents of an array type response, usually used to return a list.
@ExampleObject	Provides sample objects for use in API documentation to show examples of requests or responses.
@MediaType	Specifies the media type of the request or response.
@Link	Describes the linking relationships between APIs.
@ParameterObject	Describes composite parameter objects, typically used for complex structures in request bodies.