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

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

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

SpringDoc OpenAPI

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

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

Workspace: tessl
Visibility: Public
Created: 6 months ago
Last updated: about 2 months ago
Describes: pkg:maven/org.springdoc/springdoc-openapi@2.8.x
Publish Source: CLI
Badge