Springboot集成SpringDoc接口文檔方式

更新時(shí)間：2026年01月04日 08:42:59 作者：TheTsing

使用Spring Boot 3.0、JDK 17和Springdoc 2.2創(chuàng)建一個(gè)簡單的API文檔生成器,首先創(chuàng)建了一個(gè)Spring Boot項(xiàng)目并引入了Springdoc依賴,然后編寫了一個(gè)配置文件SpringDocConfig.java,啟動(dòng)項(xiàng)目后,可以通過訪問http://localhost:8080/swagger-ui/index.html來查看生成的API文檔

前言

基于springboot3.0+jdk17+springdoc2.2實(shí)現(xiàn)。

一、創(chuàng)建springboot項(xiàng)目，引入springdoc依賴

二、編寫springdoc配置文件SpringDocConfig.java

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.media.Content;
import io.swagger.v3.oas.models.responses.ApiResponse;
import io.swagger.v3.oas.models.security.SecurityRequirement;
import io.swagger.v3.oas.models.security.SecurityScheme;
import org.springdoc.core.customizers.GlobalOpenApiCustomizer;
import org.springdoc.core.properties.SwaggerUiConfigProperties;
import org.springdoc.core.utils.Constants;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Primary;
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpStatus;
import org.springframework.http.MediaType;

/**
 * SpringDoc配置類
 *
 * @author TheTsing
 */
@Configuration
@ConditionalOnProperty(name = Constants.SPRINGDOC_ENABLED, matchIfMissing = true)
public class SpringDocConfig {

    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                .info(new Info().title("API Documentation").version("snapshot"))
                .schemaRequirement(HttpHeaders.AUTHORIZATION,
                        new SecurityScheme()
                                // 普通 Token
                                //.name(HttpHeaders.AUTHORIZATION)
                                //.type(SecurityScheme.Type.APIKEY)
                                //.in(SecurityScheme.In.HEADER)
                                // Bearer Token
                                .name(HttpHeaders.AUTHORIZATION)
                                .type(SecurityScheme.Type.HTTP)
                                .scheme("bearer"))
                .addSecurityItem(new SecurityRequirement().addList(HttpHeaders.AUTHORIZATION));
    }

    @Bean
    public GlobalOpenApiCustomizer globalOpenApiCustomizer() {
        return openApi -> openApi.getPaths().values().stream().flatMap(pathItem -> pathItem.readOperations().stream()).forEach(operation -> {
            operation.getResponses().addApiResponse(String.valueOf(HttpStatus.BAD_REQUEST.value()),
                    new ApiResponse().description("客戶端請求存在語法錯(cuò)誤或業(yè)務(wù)異常").content(new Content().addMediaType(MediaType.TEXT_PLAIN_VALUE, new io.swagger.v3.oas.models.media.MediaType().example(HttpStatus.BAD_REQUEST.getReasonPhrase()))));
            operation.getResponses().addApiResponse(String.valueOf(HttpStatus.UNAUTHORIZED.value()),
                    new ApiResponse().description("認(rèn)證失敗").content(new Content().addMediaType(MediaType.TEXT_PLAIN_VALUE, new io.swagger.v3.oas.models.media.MediaType().example(HttpStatus.UNAUTHORIZED.getReasonPhrase()))));
            operation.getResponses().addApiResponse(String.valueOf(HttpStatus.FORBIDDEN.value()),
                    new ApiResponse().description("沒有權(quán)限").content(new Content().addMediaType(MediaType.TEXT_PLAIN_VALUE, new io.swagger.v3.oas.models.media.MediaType().example(HttpStatus.FORBIDDEN.getReasonPhrase()))));
            operation.getResponses().addApiResponse(String.valueOf(HttpStatus.INTERNAL_SERVER_ERROR.value()),
                    new ApiResponse().description("服務(wù)器內(nèi)部錯(cuò)誤").content(new Content().addMediaType(MediaType.TEXT_PLAIN_VALUE, new io.swagger.v3.oas.models.media.MediaType().example(HttpStatus.INTERNAL_SERVER_ERROR.getReasonPhrase()))));
        });
    }

    @Bean
    @Primary
    public SwaggerUiConfigProperties swaggerUiConfig() {
        SwaggerUiConfigProperties config = new SwaggerUiConfigProperties();
        config.setPersistAuthorization(true);
        config.setFilter("true");
        config.setDefaultModelsExpandDepth(-1);
        config.setDefaultModelExpandDepth(10);
        config.setDisplayRequestDuration(true);
        config.setDocExpansion("none");
        config.setShowCommonExtensions(true);
        return config;
    }

}