or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

auto-configuration.mdcontrollers.mdcore-api-generation.mdindex.mdresource-processing.mdweb-configuration.md
tile.json

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

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

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/org.springdoc/springdoc-openapi@2.8.x

To install, run

npx @tessl/cli install tessl/maven-org-springdoc--springdoc-openapi@2.8.0

index.mddocs/

SpringDoc OpenAPI

SpringDoc OpenAPI is a Java library that automates the generation of OpenAPI 3 documentation for Spring Boot applications. It examines applications at runtime to infer API semantics from Spring configurations, class structures, and annotations, generating comprehensive REST API documentation in JSON/YAML and HTML formats with integrated Swagger UI.

Package Information

  • Package Name: org.springdoc:springdoc-openapi
  • Package Type: Maven
  • Language: Java 17+
  • Installation: Add starter dependency to Maven pom.xml:

For Spring Web MVC with Swagger UI:

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.8.6</version>
</dependency>

For Spring WebFlux with Swagger UI:

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webflux-ui</artifactId>
    <version>2.8.6</version>
</dependency>

For API documentation only (no UI):

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
    <version>2.8.6</version>
</dependency>

For Gradle:

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.8.6'

Core Imports

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.security.SecurityRequirement;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springdoc.core.configuration.SpringDocConfiguration;
import org.springdoc.core.properties.SpringDocConfigProperties;
import org.springdoc.core.properties.SwaggerUiConfigProperties;

Basic Usage

SpringDoc works automatically with zero configuration for basic Spring Boot REST applications:

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

@RestController
@Tag(name = "User Management", description = "Operations for managing users")
public class UserController {
    
    @GetMapping("/users")
    @Operation(summary = "Get all users", description = "Retrieves a list of all users")
    @ApiResponse(responseCode = "200", description = "Users retrieved successfully")
    public List<User> getAllUsers() {
        return userService.findAll();
    }
    
    @PostMapping("/users")
    @Operation(summary = "Create user")
    public ResponseEntity<User> createUser(
        @Parameter(description = "User to create") @RequestBody User user) {
        User created = userService.save(user);
        return ResponseEntity.status(201).body(created);
    }
    
    @GetMapping("/users/{id}")
    @Operation(summary = "Get user by ID")
    public ResponseEntity<User> getUserById(
        @Parameter(description = "User ID") @PathVariable Long id) {
        return userService.findById(id)
            .map(ResponseEntity::ok)
            .orElse(ResponseEntity.notFound().build());
    }
}

Once the application starts, documentation is automatically available at:

  • http://localhost:8080/swagger-ui/index.html - Interactive Swagger UI interface
  • http://localhost:8080/v3/api-docs - OpenAPI JSON specification
  • http://localhost:8080/v3/api-docs.yaml - OpenAPI YAML specification

Architecture

SpringDoc OpenAPI operates through several integrated components:

  • Runtime Analysis: Scans Spring Boot applications at startup to discover REST endpoints
  • Annotation Processing: Interprets Swagger/OpenAPI annotations and Spring web annotations
  • Schema Generation: Automatically generates JSON schemas from Java classes and validation annotations
  • Document Assembly: Combines discovered APIs into complete OpenAPI specifications
  • UI Integration: Provides Swagger UI with dynamic configuration and real-time API exploration
  • Multi-Format Output: Supports JSON, YAML, and HTML documentation formats

Capabilities

Automatic API Documentation Generation

Core functionality that discovers Spring REST endpoints and generates OpenAPI specifications without manual configuration.

@Configuration
@ConditionalOnProperty(name = "springdoc.api-docs.enabled", matchIfMissing = true)
public class SpringDocConfiguration {
    @Bean
    OpenApiResource openApiResource(OpenAPI openAPI, SpringDocConfigProperties springDocConfigProperties,
        OperationService operationService, RequestMappingInfoHandlerMapping requestMappingInfoHandlerMapping,
        Optional<ActuatorProvider> actuatorProvider);
        
    @Bean
    OperationService operationService(GenericParameterService genericParameterService, 
        List<OperationCustomizer> operationCustomizers, PropertyResolverUtils propertyResolverUtils,
        SpringDocConfigProperties springDocConfigProperties);
}

@ConfigurationProperties("springdoc")
public class SpringDocConfigProperties {
    private String apiDocsPath = "/v3/api-docs";
    private boolean enabled = true;
    private String packagesToScan;
    private String pathsToMatch;
    private String packagesToExclude;
    private String pathsToExclude;
}

@RestController
public class OpenApiResource {
    public String openapiJson(HttpServletRequest request, Locale locale) throws JsonProcessingException;
    public String openapiYaml(HttpServletRequest request, Locale locale) throws JsonProcessingException;
}

Core API Generation

Swagger UI Integration

Automatic integration with Swagger UI for interactive API documentation and testing.

@Configuration
@ConditionalOnProperty(name = "springdoc.swagger-ui.enabled", matchIfMissing = true)
@ConditionalOnWebApplication(type = Type.SERVLET)
public class SwaggerConfig {
    // Swagger UI configuration and resource handling
}

@ConfigurationProperties("springdoc.swagger-ui")
public class SwaggerUiConfigProperties {
    private String path = "/swagger-ui.html";
    private boolean enabled = true;
    private String configUrl;
    private String url;
    private String[] urls;
}

Swagger UI Configuration

Spring Security Integration

Automatic detection and documentation of Spring Security configurations, including OAuth2 and JWT authentication.

@Configuration
@ConditionalOnClass(SecurityScheme.class)
public class SpringDocSecurityConfiguration {
    // Security schema detection and documentation
}

@ConfigurationProperties("springdoc.swagger-ui.oauth")
public class SwaggerUiOAuthProperties {
    private String clientId;
    private String clientSecret;
    private String realm;
    private String appName;
    private String scopeSeparator;
    private String[] scopes;
}

WebFlux Support

Full support for Spring WebFlux reactive applications with functional routing.

@Configuration
@ConditionalOnWebApplication(type = Type.REACTIVE)
public class SpringDocWebFluxConfiguration {
    // WebFlux-specific configuration
}

@RouterOperation(operation = @Operation(summary = "Get user by ID"))
public RouterFunction<ServerResponse> userRoutes() {
    return route()
        .GET("/users/{id}", this::getUserById)
        .build();
}

Validation Integration

Automatic schema generation from Bean Validation (JSR-303) annotations.

public class User {
    @NotNull
    @Size(min = 1, max = 50)
    private String username;
    
    @Email
    private String email;
    
    @Min(18)
    @Max(120)
    private Integer age;
}

Actuator Integration

Integration with Spring Boot Actuator for management endpoints and health checks.

@ControllerEndpoint(id = "swaggerui")
public class SwaggerWelcomeActuator {
    public ResponseEntity<Void> redirectToUi(HttpServletRequest request);
    public Map<String, Object> openapiJson(HttpServletRequest request);
}

Actuator Integration

Auto-Configuration

Comprehensive Spring Boot auto-configuration that adapts to different application types and deployment scenarios.

@Configuration
@ConditionalOnWebApplication
@ConditionalOnBean(SpringDocConfiguration.class)
public class SwaggerConfig {
    @Bean
    SwaggerWelcomeWebMvc swaggerWelcome(SwaggerUiConfigProperties swaggerUiConfig, 
        SpringDocConfigProperties springDocConfigProperties, SpringWebProvider springWebProvider);
        
    @Bean
    SwaggerConfigResource swaggerConfigResource(SwaggerWelcomeCommon swaggerWelcomeCommon);
    
    @Bean
    SwaggerIndexTransformer indexPageTransformer(SwaggerUiConfigProperties swaggerUiConfig, 
        SwaggerUiOAuthProperties swaggerUiOAuthProperties, SwaggerWelcomeCommon swaggerWelcomeCommon, 
        ObjectMapperProvider objectMapperProvider);
}

Auto-Configuration Details

Resource Processing

Dynamic resource transformation and web jar management for Swagger UI assets.

public class SwaggerIndexPageTransformer extends AbstractSwaggerIndexTransformer 
    implements SwaggerIndexTransformer {
    public Resource transform(HttpServletRequest request, Resource resource, 
        ResourceTransformerChain transformerChain) throws IOException;
}

public class SwaggerResourceResolver extends LiteWebJarsResourceResolver {
    protected String findWebJarResourcePath(String pathStr);
}

Resource Processing

Configuration Examples

Basic Configuration

springdoc:
  api-docs:
    path: /v3/api-docs
    enabled: true
  swagger-ui:
    path: /swagger-ui.html
    enabled: true
    try-it-out-enabled: true
    operations-sorter: method
    tags-sorter: alpha

Advanced Configuration with Security

springdoc:
  api-docs:
    path: /v3/api-docs
  swagger-ui:
    path: /swagger-ui.html
    oauth:
      client-id: my-client-id
      client-secret: my-client-secret
      realm: my-realm
      scopes: read,write
  packages-to-scan: com.example.api
  paths-to-match: /api/**

Production Configuration

springdoc:
  api-docs:
    enabled: true  
  swagger-ui:
    enabled: false  # Disable UI in production
  show-actuator: false
  use-management-port: true

management:
  server:
    port: 8081
  endpoints:
    web:
      base-path: /actuator

Supported Features

Spring Boot 3.x Support

  • Java 17+ and Jakarta EE 9 namespace
  • Native GraalVM image compilation support
  • Spring Boot 3.x auto-configuration patterns

OpenAPI 3.0 Specification

  • Complete OpenAPI 3.0.3 specification support
  • JSON and YAML output formats
  • Schema generation from Java types
  • Complex type relationships and inheritance

Validation Integration

  • JSR-303 Bean Validation annotation support
  • Automatic constraint documentation (@NotNull, @Size, @Pattern, etc.)
  • Custom validation annotation support

Advanced Features

  • Multiple OpenAPI group support for microservices
  • Custom schema and example generation
  • Internationalization (i18n) support
  • Custom Swagger UI themes and branding

Error Handling

SpringDoc provides comprehensive error handling for common deployment scenarios:

  • Missing Dependencies: Clear error messages for missing Swagger UI or core dependencies
  • Configuration Conflicts: Validation and warnings for conflicting property settings
  • Path Conflicts: Detection and resolution of conflicting URL patterns
  • Security Issues: Proper handling of security contexts and authentication flows
  • Performance Optimization: Lazy loading and caching strategies for large APIs