OpenApi 3.0(Swagger 3)实现登录端点替换ApiListingScanner方案咨询

OpenAPI 3.0 自定义登录端点文档实现方案 #

原Swagger 2.0（SpringFox 2.x）中使用的ApiListingScanner是SpringFox专属的扫描扩展类，目前行业内升级OpenAPI 3.0普遍已替换停止维护的SpringFox为SpringDoc OpenAPI，不需要寻找ApiListingScanner的对等替代类，直接使用OpenApiCustomizer接口即可实现非Controller端点（如Spring Security默认登录端点）的文档配置，实现逻辑更简洁。

具体实现步骤

1. 引入SpringDoc OpenAPI依赖（SpringBoot 2.x用1.x版本，SpringBoot 3.x用2.x版本）

<!-- SpringBoot 2.x 版本依赖 -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.7.0</version>
</dependency>

2. 编写自定义端点配置类

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.Operation;
import io.swagger.v3.oas.models.PathItem;
import io.swagger.v3.oas.models.media.Content;
import io.swagger.v3.oas.models.media.MediaType;
import io.swagger.v3.oas.models.media.Schema;
import io.swagger.v3.oas.models.parameters.RequestBody;
import io.swagger.v3.oas.models.responses.ApiResponse;
import io.swagger.v3.oas.models.responses.ApiResponses;
import org.springdoc.core.customizers.OpenApiCustomizer;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
import org.springframework.http.MediaType;

@Configuration
@Profile("!prod")
public class OpenApiLoginConfig {

    @Bean
    public OpenApiCustomizer loginEndpointCustomizer() {
        return openApi -> {
            // 构造登录请求体配置
            RequestBody requestBody = new RequestBody()
                    .description("登录请求参数")
                    .required(true)
                    .content(new Content()
                            .addMediaType(MediaType.APPLICATION_JSON_VALUE,
                                    new MediaType().schema(new Schema<>().$ref("#/components/schemas/LoginDto"))));

            // 构造登录响应配置
            ApiResponses apiResponses = new ApiResponses()
                    .addApiResponse("200", new ApiResponse()
                            .description("登录成功")
                            .content(new Content()
                                    .addMediaType(MediaType.APPLICATION_JSON_VALUE,
                                            new MediaType().schema(new Schema<>().$ref("#/components/schemas/LoginResponseDto")))));

            // 构造接口操作配置
            Operation loginOperation = new Operation()
                    .summary("用户登录")
                    .description("账号密码登录接口，登录成功返回认证凭证")
                    .tags(java.util.List.of("认证管理"))
                    .requestBody(requestBody)
                    .responses(apiResponses);

            // 将登录路径添加到OpenAPI文档
            openApi.path("/api/login", new PathItem().post(loginOperation));
        };
    }
}

如果坚持使用SpringFox 3.x版本适配OpenAPI 3.0，原ApiListingScanner类仍然可用，仅需调整对应包名即可，但SpringFox已多年未维护，不推荐继续使用。

内容的提问来源于stack exchange，提问作者patryk108