tessl/maven-org-springdoc--springdoc-openapi

Java library that automates OpenAPI 3 documentation generation for Spring Boot applications with seamless Swagger UI integration

—

Pending

Overview

Eval results

Files

Auto-Configuration

Name: tessl/maven-org-springdoc--springdoc-openapi
Author: tessl

Automatic Spring Boot configuration that sets up all necessary components for Swagger UI integration with SpringDoc OpenAPI. The configuration is condition-based and automatically adapts to different deployment scenarios.

Capabilities

SwaggerConfig

Main auto-configuration class that creates all necessary beans for Swagger UI functionality.

/**
 * Main Spring Boot auto-configuration class for Swagger UI
 * Automatically configures based on properties and runtime conditions
 */
@Configuration(proxyBeanMethods = false)
@ConditionalOnProperty(name = "springdoc.swagger-ui.enabled", matchIfMissing = true)
@ConditionalOnWebApplication(type = Type.SERVLET)
@ConditionalOnBean(SpringDocConfiguration.class)
@Lazy(false)
public class SwaggerConfig {
    
    /**
     * Creates SwaggerWelcomeWebMvc bean for standard web applications
     * @param swaggerUiConfig Swagger UI configuration properties
     * @param springDocConfigProperties SpringDoc configuration properties  
     * @param springWebProvider Spring web provider implementation
     * @return SwaggerWelcomeWebMvc instance
     */
    @Bean
    @ConditionalOnMissingBean
    @ConditionalOnProperty(name = "springdoc.use-management-port", havingValue = "false", matchIfMissing = true)
    @Lazy(false)
    SwaggerWelcomeWebMvc swaggerWelcome(SwaggerUiConfigProperties swaggerUiConfig, 
        SpringDocConfigProperties springDocConfigProperties, SpringWebProvider springWebProvider);

    /**
     * Creates Spring web provider for WebMVC applications
     * @return SpringWebMvcProvider instance
     */
    @Bean
    @ConditionalOnMissingBean
    @Lazy(false)
    public SpringWebProvider springWebProvider() {
        return new SpringWebMvcProvider();
    }

    /**
     * Creates configuration resource controller for JSON config endpoint
     * @param swaggerWelcomeCommon Common welcome functionality
     * @return SwaggerConfigResource instance
     */
    @Bean
    @ConditionalOnMissingBean
    @ConditionalOnProperty(name = "springdoc.use-management-port", havingValue = "false", matchIfMissing = true)
    @Lazy(false)
    SwaggerConfigResource swaggerConfigResource(SwaggerWelcomeCommon swaggerWelcomeCommon);

    /**
     * Creates home controller for root path redirects
     * @return SwaggerUiHome instance
     */
    @Bean
    @ConditionalOnMissingBean
    @ConditionalOnProperty(name = "springdoc.use-root-path", havingValue = "true")
    @Lazy(false)
    SwaggerUiHome swaggerUiHome();

    /**
     * Creates index page transformer for dynamic configuration injection
     * @param swaggerUiConfig Swagger UI configuration
     * @param swaggerUiOAuthProperties OAuth configuration
     * @param swaggerWelcomeCommon Common welcome functionality
     * @param objectMapperProvider JSON object mapper provider
     * @return SwaggerIndexTransformer instance
     */
    @Bean
    @ConditionalOnMissingBean
    @Lazy(false)
    SwaggerIndexTransformer indexPageTransformer(SwaggerUiConfigProperties swaggerUiConfig, 
        SwaggerUiOAuthProperties swaggerUiOAuthProperties, SwaggerWelcomeCommon swaggerWelcomeCommon, 
        ObjectMapperProvider objectMapperProvider);

    /**
     * Creates Web MVC configurer for resource handling
     * @param swaggerUiConfigProperties Swagger UI configuration
     * @param swaggerIndexTransformer Index page transformer
     * @param actuatorProvider Optional actuator provider
     * @param swaggerResourceResolver Resource resolver for web jars
     * @return SwaggerWebMvcConfigurer instance
     */
    @Bean
    @ConditionalOnMissingBean
    @Lazy(false)
    SwaggerWebMvcConfigurer swaggerWebMvcConfigurer(SwaggerUiConfigProperties swaggerUiConfigProperties,
        SwaggerIndexTransformer swaggerIndexTransformer, Optional<ActuatorProvider> actuatorProvider, 
        SwaggerResourceResolver swaggerResourceResolver);

    /**
     * Creates resource resolver for Swagger UI web jar assets
     * @param swaggerUiConfigProperties Swagger UI configuration
     * @return SwaggerResourceResolver instance
     */
    @Bean
    @ConditionalOnMissingBean
    @Lazy(false)
    SwaggerResourceResolver swaggerResourceResolver(SwaggerUiConfigProperties swaggerUiConfigProperties);
}

Actuator Configuration

Nested configuration class for Spring Boot Actuator integration when management port is enabled.

/**
 * Actuator-specific configuration for Swagger UI on management port
 * Only active when management port is different from main application port
 */
@ConditionalOnProperty("springdoc.use-management-port")
@ConditionalOnClass(WebMvcEndpointHandlerMapping.class)
@ConditionalOnManagementPort(ManagementPortType.DIFFERENT)
static class SwaggerActuatorWelcomeConfiguration {

    /**
     * Creates actuator welcome controller for management port deployment
     * @param swaggerUiConfig Swagger UI configuration
     * @param springDocConfigProperties SpringDoc configuration
     * @param webEndpointProperties Actuator web endpoint properties
     * @return SwaggerWelcomeActuator instance
     */
    @Bean
    @ConditionalOnMissingBean
    @Lazy(false)
    SwaggerWelcomeActuator swaggerActuatorWelcome(SwaggerUiConfigProperties swaggerUiConfig, 
        SpringDocConfigProperties springDocConfigProperties, WebEndpointProperties webEndpointProperties);
}

Configuration Conditions

Property-Based Conditions

// Enables/disables Swagger UI entirely
@ConditionalOnProperty(name = "springdoc.swagger-ui.enabled", matchIfMissing = true)

// Controls whether to use management port for Swagger UI
@ConditionalOnProperty(name = "springdoc.use-management-port", havingValue = "false", matchIfMissing = true)

// Enables root path redirect to Swagger UI
@ConditionalOnProperty(name = "springdoc.use-root-path", havingValue = "true")

// Enables actuator-specific configuration
@ConditionalOnProperty("springdoc.use-management-port")

Environment-Based Conditions

// Only activates for servlet-based web applications
@ConditionalOnWebApplication(type = Type.SERVLET)

// Requires SpringDoc core configuration to be present
@ConditionalOnBean(SpringDocConfiguration.class)

// Only when Spring Boot Actuator WebMVC is available
@ConditionalOnClass(WebMvcEndpointHandlerMapping.class)

// Only when management port is different from main port
@ConditionalOnManagementPort(ManagementPortType.DIFFERENT)

// Prevents duplicate bean creation
@ConditionalOnMissingBean

Bean Dependencies

The auto-configuration creates beans with specific dependency relationships:

SwaggerConfig
├── swaggerWelcome() → SwaggerWelcomeWebMvc
│   ├── SwaggerUiConfigProperties (injected)
│   ├── SpringDocConfigProperties (injected)
│   └── SpringWebProvider (from springWebProvider())
├── springWebProvider() → SpringWebMvcProvider
├── swaggerConfigResource() → SwaggerConfigResource
│   └── SwaggerWelcomeCommon (base class dependency)
├── swaggerUiHome() → SwaggerUiHome
├── indexPageTransformer() → SwaggerIndexPageTransformer
│   ├── SwaggerUiConfigProperties (injected)
│   ├── SwaggerUiOAuthProperties (injected)
│   ├── SwaggerWelcomeCommon (injected)
│   └── ObjectMapperProvider (injected)
├── swaggerWebMvcConfigurer() → SwaggerWebMvcConfigurer
│   ├── SwaggerUiConfigProperties (injected)
│   ├── SwaggerIndexTransformer (from indexPageTransformer())
│   ├── Optional<ActuatorProvider> (injected)
│   └── SwaggerResourceResolver (from swaggerResourceResolver())
└── swaggerResourceResolver() → SwaggerResourceResolver
    └── SwaggerUiConfigProperties (injected)

Usage Examples

Basic Auto-Configuration

Most applications require no additional configuration:

@SpringBootApplication
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

Custom Configuration Override

Override specific beans when customization is needed:

@Configuration
public class CustomSwaggerConfig {
    
    @Bean
    @Primary
    public SwaggerWelcomeWebMvc customSwaggerWelcome(
        SwaggerUiConfigProperties swaggerUiConfig,
        SpringDocConfigProperties springDocConfigProperties, 
        SpringWebProvider springWebProvider) {
        // Custom implementation
        return new CustomSwaggerWelcomeWebMvc(swaggerUiConfig, springDocConfigProperties, springWebProvider);
    }
}

Conditional Bean Registration

@Configuration
@ConditionalOnProperty("app.swagger.custom-theme")
public class CustomThemeConfig {
    
    @Bean
    public SwaggerIndexTransformer customThemeTransformer() {
        return new CustomThemeIndexTransformer();
    }
}

Configuration Properties Integration

The auto-configuration integrates with Spring Boot's configuration property system:

springdoc:
  swagger-ui:
    enabled: true  # Controls @ConditionalOnProperty
    path: /swagger-ui.html
  use-management-port: false  # Controls actuator configuration
  use-root-path: false  # Controls SwaggerUiHome creation
  
management:
  server:
    port: 8081  # Triggers actuator-specific configuration when different from server.port

Install with Tessl CLI

npx tessl i tessl/maven-org-springdoc--springdoc-openapi

docs

auto-configuration.md

controllers.md

core-api-generation.md

index.md

resource-processing.md

web-configuration.md

tile.json

tessl/maven-org-springdoc--springdoc-openapi