Initial commit
This commit is contained in:
Zhongwei Li
624
skills/spring-boot-openapi-documentation/SKILL.md
Normal file
624
skills/spring-boot-openapi-documentation/SKILL.md
Normal file
@@ -0,0 +1,624 @@
|
||||
---
|
||||
name: spring-boot-openapi-documentation
|
||||
description: Generate comprehensive REST API documentation using SpringDoc OpenAPI 3.0 and Swagger UI in Spring Boot 3.x applications. Use when setting up API documentation, configuring Swagger UI, adding OpenAPI annotations, implementing security documentation, or enhancing REST endpoints with examples and schemas.
|
||||
allowed-tools: Read, Write, Bash, Grep
|
||||
category: backend
|
||||
tags: [spring-boot, openapi, swagger, api-documentation, springdoc]
|
||||
version: 1.1.0
|
||||
---
|
||||
|
||||
# Spring Boot OpenAPI Documentation with SpringDoc
|
||||
|
||||
Implement comprehensive REST API documentation using SpringDoc OpenAPI 3.0 and Swagger UI in Spring Boot 3.x applications.
|
||||
|
||||
## When to Use
|
||||
|
||||
Use this skill when you need to:
|
||||
- Set up SpringDoc OpenAPI in Spring Boot 3.x projects
|
||||
- Generate OpenAPI 3.0 specifications for REST APIs
|
||||
- Configure and customize Swagger UI
|
||||
- Add detailed API documentation with annotations
|
||||
- Document request/response models with validation
|
||||
- Implement API security documentation (JWT, OAuth2, Basic Auth)
|
||||
- Document pageable and sortable endpoints
|
||||
- Add examples and schemas to API endpoints
|
||||
- Customize OpenAPI definitions programmatically
|
||||
- Generate API documentation for WebMvc or WebFlux applications
|
||||
- Support multiple API groups and versions
|
||||
- Document error responses and exception handlers
|
||||
- Add JSR-303 Bean Validation to API documentation
|
||||
- Support Kotlin-based Spring Boot APIs
|
||||
|
||||
## Setup Dependencies
|
||||
|
||||
### Add Maven Dependencies
|
||||
|
||||
```xml
|
||||
<!-- Standard WebMVC support -->
|
||||
<dependency>
|
||||
<groupId>org.springdoc</groupId>
|
||||
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
|
||||
<version>2.8.13</version> // Use latest stable version
|
||||
</dependency>
|
||||
|
||||
<!-- Optional: therapi-runtime-javadoc for JavaDoc support -->
|
||||
<dependency>
|
||||
<groupId>com.github.therapi</groupId>
|
||||
<artifactId>therapi-runtime-javadoc</artifactId>
|
||||
<version>0.15.0</version> // Use latest stable version
|
||||
<scope>provided</scope>
|
||||
</dependency>
|
||||
|
||||
<!-- WebFlux support -->
|
||||
<dependency>
|
||||
<groupId>org.springdoc</groupId>
|
||||
<artifactId>springdoc-openapi-starter-webflux-ui</artifactId>
|
||||
<version>2.8.13</version> // Use latest stable version
|
||||
</dependency>
|
||||
```
|
||||
|
||||
### Add Gradle Dependencies
|
||||
|
||||
```gradle
|
||||
// Standard WebMVC support
|
||||
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.8.13'
|
||||
|
||||
// Optional: therapi-runtime-javadoc for JavaDoc support
|
||||
implementation 'com.github.therapi:therapi-runtime-javadoc:0.15.0'
|
||||
|
||||
// WebFlux support
|
||||
implementation 'org.springdoc:springdoc-openapi-starter-webflux-ui:2.8.13'
|
||||
```
|
||||
|
||||
## Configure SpringDoc
|
||||
|
||||
### Basic Configuration
|
||||
|
||||
```properties
|
||||
# application.properties
|
||||
springdoc.api-docs.path=/api-docs
|
||||
springdoc.swagger-ui.path=/swagger-ui-custom.html
|
||||
springdoc.swagger-ui.operationsSorter=method
|
||||
springdoc.swagger-ui.tagsSorter=alpha
|
||||
springdoc.swagger-ui.enabled=true
|
||||
springdoc.api-docs.enabled=true
|
||||
springdoc.packages-to-scan=com.example.controller
|
||||
springdoc.paths-to-match=/api/**
|
||||
```
|
||||
|
||||
```yaml
|
||||
# application.yml
|
||||
springdoc:
|
||||
api-docs:
|
||||
path: /api-docs
|
||||
enabled: true
|
||||
swagger-ui:
|
||||
path: /swagger-ui.html
|
||||
enabled: true
|
||||
operationsSorter: method
|
||||
tagsSorter: alpha
|
||||
tryItOutEnabled: true
|
||||
packages-to-scan: com.example.controller
|
||||
paths-to-match: /api/**
|
||||
```
|
||||
|
||||
### Access Endpoints
|
||||
|
||||
After configuration:
|
||||
- **OpenAPI JSON**: `http://localhost:8080/v3/api-docs`
|
||||
- **OpenAPI YAML**: `http://localhost:8080/v3/api-docs.yaml`
|
||||
- **Swagger UI**: `http://localhost:8080/swagger-ui/index.html`
|
||||
|
||||
## Document Controllers
|
||||
|
||||
### Basic Controller Documentation
|
||||
|
||||
```java
|
||||
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.responses.ApiResponses;
|
||||
import io.swagger.v3.oas.annotations.tags.Tag;
|
||||
import org.springframework.web.bind.annotation.*;
|
||||
|
||||
@RestController
|
||||
@RequestMapping("/api/books")
|
||||
@Tag(name = "Book", description = "Book management APIs")
|
||||
public class BookController {
|
||||
|
||||
@Operation(
|
||||
summary = "Retrieve a book by ID",
|
||||
description = "Get a Book object by specifying its ID. The response includes id, title, author and description."
|
||||
)
|
||||
@ApiResponses(value = {
|
||||
@ApiResponse(
|
||||
responseCode = "200",
|
||||
description = "Successfully retrieved book",
|
||||
content = @Content(schema = @Schema(implementation = Book.class))
|
||||
),
|
||||
@ApiResponse(
|
||||
responseCode = "404",
|
||||
description = "Book not found"
|
||||
)
|
||||
})
|
||||
@GetMapping("/{id}")
|
||||
public Book findById(
|
||||
@Parameter(description = "ID of book to retrieve", required = true)
|
||||
@PathVariable Long id
|
||||
) {
|
||||
return repository.findById(id)
|
||||
.orElseThrow(() -> new BookNotFoundException());
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Document Request Bodies
|
||||
|
||||
```java
|
||||
import io.swagger.v3.oas.annotations.parameters.RequestBody;
|
||||
import io.swagger.v3.oas.annotations.media.ExampleObject;
|
||||
|
||||
@Operation(summary = "Create a new book")
|
||||
@PostMapping
|
||||
@ResponseStatus(HttpStatus.CREATED)
|
||||
public Book createBook(
|
||||
@RequestBody(
|
||||
description = "Book to create",
|
||||
required = true,
|
||||
content = @Content(
|
||||
schema = @Schema(implementation = Book.class),
|
||||
examples = @ExampleObject(
|
||||
value = """
|
||||
{
|
||||
"title": "Clean Code",
|
||||
"author": "Robert C. Martin",
|
||||
"isbn": "978-0132350884",
|
||||
"description": "A handbook of agile software craftsmanship"
|
||||
}
|
||||
"""
|
||||
)
|
||||
)
|
||||
)
|
||||
Book book
|
||||
) {
|
||||
return repository.save(book);
|
||||
}
|
||||
```
|
||||
|
||||
## Document Models
|
||||
|
||||
### Entity with Validation
|
||||
|
||||
```java
|
||||
import io.swagger.v3.oas.annotations.media.Schema;
|
||||
import jakarta.validation.constraints.*;
|
||||
|
||||
@Entity
|
||||
@Schema(description = "Book entity representing a published book")
|
||||
public class Book {
|
||||
|
||||
@Id
|
||||
@GeneratedValue(strategy = GenerationType.IDENTITY)
|
||||
@Schema(description = "Unique identifier", example = "1", accessMode = Schema.AccessMode.READ_ONLY)
|
||||
private Long id;
|
||||
|
||||
@NotBlank(message = "Title is required")
|
||||
@Size(min = 1, max = 200)
|
||||
@Schema(description = "Book title", example = "Clean Code", required = true, maxLength = 200)
|
||||
private String title;
|
||||
|
||||
@Pattern(regexp = "^(?:ISBN(?:-1[03])?:? )?(?=[0-9X]{10}$|(?=(?:[0-9]+[- ]){3})[- 0-9X]{13}$|97[89][0-9]{10}$|(?=(?:[0-9]+[- ]){4})[- 0-9]{17}$)(?:97[89][- ]?)?[0-9]{1,5}[- ]?[0-9]+[- ]?[0-9]+[- ]?[0-9X]$")
|
||||
@Schema(description = "ISBN number", example = "978-0132350884")
|
||||
private String isbn;
|
||||
|
||||
// Additional fields, constructors, getters, setters
|
||||
}
|
||||
```
|
||||
|
||||
### Hidden Fields
|
||||
|
||||
```java
|
||||
@Schema(hidden = true)
|
||||
private String internalField;
|
||||
|
||||
@JsonIgnore
|
||||
@Schema(accessMode = Schema.AccessMode.READ_ONLY)
|
||||
private LocalDateTime createdAt;
|
||||
```
|
||||
|
||||
## Document Security
|
||||
|
||||
### JWT Bearer Authentication
|
||||
|
||||
```java
|
||||
import io.swagger.v3.oas.annotations.security.SecurityRequirement;
|
||||
import io.swagger.v3.oas.models.Components;
|
||||
import io.swagger.v3.oas.models.security.SecurityScheme;
|
||||
|
||||
@Configuration
|
||||
public class OpenAPISecurityConfig {
|
||||
|
||||
@Bean
|
||||
public OpenAPI customOpenAPI() {
|
||||
return new OpenAPI()
|
||||
.components(new Components()
|
||||
.addSecuritySchemes("bearer-jwt", new SecurityScheme()
|
||||
.type(SecurityScheme.Type.HTTP)
|
||||
.scheme("bearer")
|
||||
.bearerFormat("JWT")
|
||||
.description("JWT authentication")
|
||||
)
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
// Apply security requirement
|
||||
@RestController
|
||||
@RequestMapping("/api/books")
|
||||
@SecurityRequirement(name = "bearer-jwt")
|
||||
public class BookController {
|
||||
// All endpoints require JWT authentication
|
||||
}
|
||||
```
|
||||
|
||||
### OAuth2 Configuration
|
||||
|
||||
```java
|
||||
import io.swagger.v3.oas.models.security.OAuthFlow;
|
||||
import io.swagger.v3.oas.models.security.OAuthFlows;
|
||||
import io.swagger.v3.oas.models.security.Scopes;
|
||||
|
||||
@Bean
|
||||
public OpenAPI customOpenAPI() {
|
||||
return new OpenAPI()
|
||||
.components(new Components()
|
||||
.addSecuritySchemes("oauth2", new SecurityScheme()
|
||||
.type(SecurityScheme.Type.OAUTH2)
|
||||
.flows(new OAuthFlows()
|
||||
.authorizationCode(new OAuthFlow()
|
||||
.authorizationUrl("https://auth.example.com/oauth/authorize")
|
||||
.tokenUrl("https://auth.example.com/oauth/token")
|
||||
.scopes(new Scopes()
|
||||
.addString("read", "Read access")
|
||||
.addString("write", "Write access")
|
||||
)
|
||||
)
|
||||
)
|
||||
)
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
## Document Pagination
|
||||
|
||||
### Spring Data Pageable Support
|
||||
|
||||
```java
|
||||
import org.springdoc.core.annotations.ParameterObject;
|
||||
import org.springframework.data.domain.Page;
|
||||
import org.springframework.data.domain.Pageable;
|
||||
|
||||
@Operation(summary = "Get paginated list of books")
|
||||
@GetMapping("/paginated")
|
||||
public Page<Book> findAllPaginated(
|
||||
@ParameterObject Pageable pageable
|
||||
) {
|
||||
return repository.findAll(pageable);
|
||||
}
|
||||
```
|
||||
|
||||
## Advanced Configuration
|
||||
|
||||
### Multiple API Groups
|
||||
|
||||
```java
|
||||
import org.springdoc.core.models.GroupedOpenApi;
|
||||
|
||||
@Bean
|
||||
public GroupedOpenApi publicApi() {
|
||||
return GroupedOpenApi.builder()
|
||||
.group("public")
|
||||
.pathsToMatch("/api/public/**")
|
||||
.build();
|
||||
}
|
||||
|
||||
@Bean
|
||||
public GroupedOpenApi adminApi() {
|
||||
return GroupedOpenApi.builder()
|
||||
.group("admin")
|
||||
.pathsToMatch("/api/admin/**")
|
||||
.build();
|
||||
}
|
||||
```
|
||||
|
||||
### Custom Operation Customizer
|
||||
|
||||
```java
|
||||
import org.springdoc.core.customizers.OperationCustomizer;
|
||||
|
||||
@Bean
|
||||
public OperationCustomizer customizeOperation() {
|
||||
return (operation, handlerMethod) -> {
|
||||
operation.addExtension("x-custom-field", "custom-value");
|
||||
return operation;
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### Hide Endpoints
|
||||
|
||||
```java
|
||||
@Operation(hidden = true)
|
||||
@GetMapping("/internal")
|
||||
public String internalEndpoint() {
|
||||
return "Hidden from docs";
|
||||
}
|
||||
|
||||
// Hide entire controller
|
||||
@Hidden
|
||||
@RestController
|
||||
public class InternalController {
|
||||
// All endpoints hidden
|
||||
}
|
||||
```
|
||||
|
||||
## Document Exception Responses
|
||||
|
||||
### Global Exception Handler
|
||||
|
||||
```java
|
||||
import org.springframework.web.bind.annotation.ExceptionHandler;
|
||||
import org.springframework.web.bind.annotation.ResponseStatus;
|
||||
import org.springframework.web.bind.annotation.RestControllerAdvice;
|
||||
|
||||
@RestControllerAdvice
|
||||
public class GlobalExceptionHandler {
|
||||
|
||||
@ExceptionHandler(BookNotFoundException.class)
|
||||
@ResponseStatus(HttpStatus.NOT_FOUND)
|
||||
@Operation(hidden = true)
|
||||
public ErrorResponse handleBookNotFound(BookNotFoundException ex) {
|
||||
return new ErrorResponse("BOOK_NOT_FOUND", ex.getMessage());
|
||||
}
|
||||
|
||||
@ExceptionHandler(ValidationException.class)
|
||||
@ResponseStatus(HttpStatus.BAD_REQUEST)
|
||||
@Operation(hidden = true)
|
||||
public ErrorResponse handleValidation(ValidationException ex) {
|
||||
return new ErrorResponse("VALIDATION_ERROR", ex.getMessage());
|
||||
}
|
||||
}
|
||||
|
||||
@Schema(description = "Error response")
|
||||
public record ErrorResponse(
|
||||
@Schema(description = "Error code", example = "BOOK_NOT_FOUND")
|
||||
String code,
|
||||
|
||||
@Schema(description = "Error message", example = "Book with ID 123 not found")
|
||||
String message,
|
||||
|
||||
@Schema(description = "Timestamp", example = "2024-01-15T10:30:00Z")
|
||||
LocalDateTime timestamp
|
||||
) {}
|
||||
```
|
||||
|
||||
## Build Integration
|
||||
|
||||
### Maven Plugin
|
||||
|
||||
```xml
|
||||
<plugin>
|
||||
<groupId>org.springdoc</groupId>
|
||||
<artifactId>springdoc-openapi-maven-plugin</artifactId>
|
||||
<version>1.4</version>
|
||||
<executions>
|
||||
<execution>
|
||||
<phase>integration-test</phase>
|
||||
<goals>
|
||||
<goal>generate</goal>
|
||||
</goals>
|
||||
</execution>
|
||||
</executions>
|
||||
<configuration>
|
||||
<apiDocsUrl>http://localhost:8080/v3/api-docs</apiDocsUrl>
|
||||
<outputFileName>openapi.json</outputFileName>
|
||||
<outputDir>${project.build.directory}</outputDir>
|
||||
</configuration>
|
||||
</plugin>
|
||||
```
|
||||
|
||||
### Gradle Plugin
|
||||
|
||||
```gradle
|
||||
plugins {
|
||||
id 'org.springdoc.openapi-gradle-plugin' version '1.9.0'
|
||||
}
|
||||
|
||||
openApi {
|
||||
apiDocsUrl = "http://localhost:8080/v3/api-docs"
|
||||
outputDir = file("$buildDir/docs")
|
||||
outputFileName = "openapi.json"
|
||||
}
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
### Complete REST Controller Example
|
||||
|
||||
```java
|
||||
import io.swagger.v3.oas.annotations.Operation;
|
||||
import io.swagger.v3.oas.annotations.Parameter;
|
||||
import io.swagger.v3.oas.annotations.media.Content;
|
||||
import io.swagger.v3.oas.annotations.media.Schema;
|
||||
import io.swagger.v3.oas.annotations.responses.ApiResponse;
|
||||
import io.swagger.v3.oas.annotations.responses.ApiResponses;
|
||||
import io.swagger.v3.oas.annotations.tags.Tag;
|
||||
import io.swagger.v3.oas.annotations.security.SecurityRequirement;
|
||||
import org.springframework.data.domain.Page;
|
||||
import org.springframework.data.domain.Pageable;
|
||||
import org.springdoc.core.annotations.ParameterObject;
|
||||
import org.springframework.web.bind.annotation.*;
|
||||
import jakarta.validation.Valid;
|
||||
|
||||
@RestController
|
||||
@RequestMapping("/api/books")
|
||||
@Tag(name = "Book", description = "Book management APIs")
|
||||
@SecurityRequirement(name = "bearer-jwt")
|
||||
public class BookController {
|
||||
|
||||
private final BookService bookService;
|
||||
|
||||
public BookController(BookService bookService) {
|
||||
this.bookService = bookService;
|
||||
}
|
||||
|
||||
@Operation(summary = "Get all books")
|
||||
@ApiResponses(value = {
|
||||
@ApiResponse(
|
||||
responseCode = "200",
|
||||
description = "Found all books",
|
||||
content = @Content(
|
||||
mediaType = "application/json",
|
||||
array = @ArraySchema(schema = @Schema(implementation = Book.class))
|
||||
)
|
||||
)
|
||||
})
|
||||
@GetMapping
|
||||
public List<Book> getAllBooks() {
|
||||
return bookService.getAllBooks();
|
||||
}
|
||||
|
||||
@Operation(summary = "Get paginated books")
|
||||
@GetMapping("/paginated")
|
||||
public Page<Book> getBooksPaginated(@ParameterObject Pageable pageable) {
|
||||
return bookService.getBooksPaginated(pageable);
|
||||
}
|
||||
|
||||
@Operation(summary = "Get book by ID")
|
||||
@ApiResponses(value = {
|
||||
@ApiResponse(responseCode = "200", description = "Book found"),
|
||||
@ApiResponse(responseCode = "404", description = "Book not found")
|
||||
})
|
||||
@GetMapping("/{id}")
|
||||
public Book getBookById(@PathVariable Long id) {
|
||||
return bookService.getBookById(id);
|
||||
}
|
||||
|
||||
@Operation(summary = "Create new book")
|
||||
@ApiResponses(value = {
|
||||
@ApiResponse(responseCode = "201", description = "Book created successfully"),
|
||||
@ApiResponse(responseCode = "400", description = "Invalid input")
|
||||
})
|
||||
@PostMapping
|
||||
@ResponseStatus(HttpStatus.CREATED)
|
||||
public Book createBook(@Valid @RequestBody Book book) {
|
||||
return bookService.createBook(book);
|
||||
}
|
||||
|
||||
@Operation(summary = "Update book")
|
||||
@ApiResponses(value = {
|
||||
@ApiResponse(responseCode = "200", description = "Book updated"),
|
||||
@ApiResponse(responseCode = "404", description = "Book not found")
|
||||
})
|
||||
@PutMapping("/{id}")
|
||||
public Book updateBook(@PathVariable Long id, @Valid @RequestBody Book book) {
|
||||
return bookService.updateBook(id, book);
|
||||
}
|
||||
|
||||
@Operation(summary = "Delete book")
|
||||
@ApiResponses(value = {
|
||||
@ApiResponse(responseCode = "204", description = "Book deleted"),
|
||||
@ApiResponse(responseCode = "404", description = "Book not found")
|
||||
})
|
||||
@DeleteMapping("/{id}")
|
||||
@ResponseStatus(HttpStatus.NO_CONTENT)
|
||||
public void deleteBook(@PathVariable Long id) {
|
||||
bookService.deleteBook(id);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Use descriptive operation summaries and descriptions**
|
||||
- Summary: Short, clear statement (< 120 chars)
|
||||
- Description: Detailed explanation with use cases
|
||||
|
||||
2. **Document all response codes**
|
||||
- Include success (2xx), client errors (4xx), server errors (5xx)
|
||||
- Provide meaningful descriptions for each
|
||||
|
||||
3. **Add examples to request/response bodies**
|
||||
- Use `@ExampleObject` for realistic examples
|
||||
- Include edge cases when relevant
|
||||
|
||||
4. **Leverage JSR-303 validation annotations**
|
||||
- SpringDoc auto-generates constraints from validation annotations
|
||||
- Reduces duplication between code and documentation
|
||||
|
||||
5. **Use `@ParameterObject` for complex parameters**
|
||||
- Especially useful for Pageable, custom filter objects
|
||||
- Keeps controller methods clean
|
||||
|
||||
6. **Group related endpoints with @Tag**
|
||||
- Organize API by domain entities or features
|
||||
- Use consistent tag names across controllers
|
||||
|
||||
7. **Document security requirements**
|
||||
- Apply `@SecurityRequirement` where authentication needed
|
||||
- Configure security schemes globally in OpenAPI bean
|
||||
|
||||
8. **Hide internal/admin endpoints appropriately**
|
||||
- Use `@Hidden` or create separate API groups
|
||||
- Prevent exposing internal implementation details
|
||||
|
||||
9. **Customize Swagger UI for better UX**
|
||||
- Enable filtering, sorting, try-it-out features
|
||||
- Set appropriate default behaviors
|
||||
|
||||
10. **Version your API documentation**
|
||||
- Include version in OpenAPI Info
|
||||
- Consider multiple API groups for versioned APIs
|
||||
|
||||
## Common Annotations Reference
|
||||
|
||||
### Core Annotations
|
||||
|
||||
- `@Tag`: Group operations under a tag
|
||||
- `@Operation`: Describe a single API operation
|
||||
- `@ApiResponse` / `@ApiResponses`: Document response codes
|
||||
- `@Parameter`: Document a single parameter
|
||||
- `@RequestBody`: Document request body (OpenAPI version)
|
||||
- `@Schema`: Document model schema
|
||||
- `@SecurityRequirement`: Apply security to operations
|
||||
- `@Hidden`: Hide from documentation
|
||||
- `@ParameterObject`: Document complex objects as parameters
|
||||
|
||||
### Validation Annotations (Auto-documented)
|
||||
|
||||
- `@NotNull`, `@NotBlank`, `@NotEmpty`: Required fields
|
||||
- `@Size(min, max)`: String/collection length constraints
|
||||
- `@Min`, `@Max`: Numeric range constraints
|
||||
- `@Pattern`: Regex validation
|
||||
- `@Email`: Email validation
|
||||
- `@DecimalMin`, `@DecimalMax`: Decimal constraints
|
||||
- `@Positive`, `@PositiveOrZero`, `@Negative`, `@NegativeOrZero`
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
For common issues and solutions, refer to the troubleshooting guide in @references/troubleshooting.md
|
||||
|
||||
## Related Skills
|
||||
|
||||
- `spring-boot-rest-api-standards` - REST API design standards
|
||||
- `spring-boot-dependency-injection` - Dependency injection patterns
|
||||
- `unit-test-controller-layer` - Testing REST controllers
|
||||
- `spring-boot-actuator` - Production monitoring and management
|
||||
|
||||
## References
|
||||
|
||||
- [Comprehensive SpringDoc documentation](references/springdoc-official.md)
|
||||
- [Common issues and solutions](references/troubleshooting.md)
|
||||
- [SpringDoc Official Documentation](https://springdoc.org/)
|
||||
- [OpenAPI 3.0 Specification](https://swagger.io/specification/)
|
||||
- [Swagger UI Configuration](https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/)
|
||||
@@ -0,0 +1,618 @@
|
||||
# SpringDoc OpenAPI Official Documentation
|
||||
|
||||
## Overview
|
||||
|
||||
SpringDoc OpenAPI is a Java library that automates API documentation generation for Spring Boot projects. It examines applications at runtime to infer API semantics based on Spring configurations and annotations.
|
||||
|
||||
## Key Features
|
||||
|
||||
- **OpenAPI 3 support** with Spring Boot v3 (Java 17 & Jakarta EE 9)
|
||||
- **Swagger UI integration** for interactive API documentation
|
||||
- **Scalar support** as an alternative UI
|
||||
- **Multiple endpoint support** with grouping capabilities
|
||||
- **Security integration** with Spring Security and OAuth2
|
||||
- **Functional endpoints** support for WebFlux and WebMvc.fn
|
||||
|
||||
## Dependencies
|
||||
|
||||
### Maven (Spring Boot 3.x)
|
||||
```xml
|
||||
<dependency>
|
||||
<groupId>org.springdoc</groupId>
|
||||
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
|
||||
<version>2.8.13</version>
|
||||
</dependency>
|
||||
```
|
||||
|
||||
### Gradle (Spring Boot 3.x)
|
||||
```gradle
|
||||
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.8.13'
|
||||
```
|
||||
|
||||
### WebFlux Support
|
||||
```xml
|
||||
<dependency>
|
||||
<groupId>org.springdoc</groupId>
|
||||
<artifactId>springdoc-openapi-starter-webflux-ui</artifactId>
|
||||
<version>2.8.13</version>
|
||||
</dependency>
|
||||
```
|
||||
|
||||
## Default Endpoints
|
||||
|
||||
After adding the dependency:
|
||||
- **OpenAPI JSON**: `http://localhost:8080/v3/api-docs`
|
||||
- **OpenAPI YAML**: `http://localhost:8080/v3/api-docs.yaml`
|
||||
- **Swagger UI**: `http://localhost:8080/swagger-ui/index.html`
|
||||
|
||||
## Compatibility Matrix
|
||||
|
||||
| Spring Boot Version | SpringDoc OpenAPI Version |
|
||||
|---------------------|---------------------------|
|
||||
| 3.4.x | 2.7.x - 2.8.x |
|
||||
| 3.3.x | 2.6.x |
|
||||
| 3.2.x | 2.3.x - 2.5.x |
|
||||
| 3.1.x | 2.2.x |
|
||||
| 3.0.x | 2.0.x - 2.1.x |
|
||||
|
||||
## Basic Configuration
|
||||
|
||||
### application.properties
|
||||
```properties
|
||||
# Custom API docs path
|
||||
springdoc.api-docs.path=/api-docs
|
||||
|
||||
# Custom Swagger UI path
|
||||
springdoc.swagger-ui.path=/swagger-ui-custom.html
|
||||
|
||||
# Sort operations by HTTP method
|
||||
springdoc.swagger-ui.operationsSorter=method
|
||||
|
||||
# Sort tags alphabetically
|
||||
springdoc.swagger-ui.tagsSorter=alpha
|
||||
|
||||
# Enable/disable Swagger UI
|
||||
springdoc.swagger-ui.enabled=true
|
||||
|
||||
# Disable springdoc-openapi endpoints
|
||||
springdoc.api-docs.enabled=false
|
||||
|
||||
# Show actuator endpoints in documentation
|
||||
springdoc.show-actuator=true
|
||||
|
||||
# Packages to scan
|
||||
springdoc.packages-to-scan=com.example.controller
|
||||
|
||||
# Paths to match
|
||||
springdoc.paths-to-match=/api/**,/public/**
|
||||
|
||||
# Default response messages
|
||||
springdoc.default-produces-media-type=application/json
|
||||
springdoc.default-consumes-media-type=application/json
|
||||
```
|
||||
|
||||
### application.yml
|
||||
```yaml
|
||||
springdoc:
|
||||
api-docs:
|
||||
path: /api-docs
|
||||
enabled: true
|
||||
swagger-ui:
|
||||
path: /swagger-ui.html
|
||||
enabled: true
|
||||
operationsSorter: method
|
||||
tagsSorter: alpha
|
||||
tryItOutEnabled: true
|
||||
filter: true
|
||||
displayRequestDuration: true
|
||||
packages-to-scan: com.example.controller
|
||||
paths-to-match: /api/**
|
||||
show-actuator: false
|
||||
```
|
||||
|
||||
## OpenAPI Information Configuration
|
||||
|
||||
### Programmatic Configuration
|
||||
```java
|
||||
import io.swagger.v3.oas.models.OpenAPI;
|
||||
import io.swagger.v3.oas.models.info.Info;
|
||||
import io.swagger.v3.oas.models.info.Contact;
|
||||
import io.swagger.v3.oas.models.info.License;
|
||||
import io.swagger.v3.oas.models.servers.Server;
|
||||
import org.springframework.context.annotation.Bean;
|
||||
import org.springframework.context.annotation.Configuration;
|
||||
|
||||
@Configuration
|
||||
public class OpenAPIConfig {
|
||||
|
||||
@Bean
|
||||
public OpenAPI customOpenAPI() {
|
||||
return new OpenAPI()
|
||||
.info(new Info()
|
||||
.title("Book API")
|
||||
.version("1.0")
|
||||
.description("REST API for managing books")
|
||||
.termsOfService("https://example.com/terms")
|
||||
.contact(new Contact()
|
||||
.name("API Support")
|
||||
.url("https://example.com/support")
|
||||
.email("support@example.com"))
|
||||
.license(new License()
|
||||
.name("Apache 2.0")
|
||||
.url("https://www.apache.org/licenses/LICENSE-2.0.html")))
|
||||
.servers(List.of(
|
||||
new Server().url("http://localhost:8080").description("Development server"),
|
||||
new Server().url("https://api.example.com").description("Production server")
|
||||
));
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Controller Documentation
|
||||
|
||||
### Basic Controller Documentation
|
||||
```java
|
||||
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.responses.ApiResponses;
|
||||
import io.swagger.v3.oas.annotations.tags.Tag;
|
||||
import io.swagger.v3.oas.annotations.media.Content;
|
||||
import io.swagger.v3.oas.annotations.media.Schema;
|
||||
import org.springframework.web.bind.annotation.*;
|
||||
|
||||
@RestController
|
||||
@RequestMapping("/api/books")
|
||||
@Tag(name = "Book", description = "Book management APIs")
|
||||
public class BookController {
|
||||
|
||||
private final BookRepository repository;
|
||||
|
||||
public BookController(BookRepository repository) {
|
||||
this.repository = repository;
|
||||
}
|
||||
|
||||
@Operation(
|
||||
summary = "Retrieve a book by ID",
|
||||
description = "Get a Book object by specifying its ID. The response is Book object with id, title, author and description."
|
||||
)
|
||||
@ApiResponses(value = {
|
||||
@ApiResponse(
|
||||
responseCode = "200",
|
||||
description = "Successfully retrieved book",
|
||||
content = @Content(
|
||||
mediaType = "application/json",
|
||||
schema = @Schema(implementation = Book.class)
|
||||
)
|
||||
),
|
||||
@ApiResponse(
|
||||
responseCode = "404",
|
||||
description = "Book not found",
|
||||
content = @Content
|
||||
),
|
||||
@ApiResponse(
|
||||
responseCode = "500",
|
||||
description = "Internal server error",
|
||||
content = @Content
|
||||
)
|
||||
})
|
||||
@GetMapping("/{id}")
|
||||
public Book findById(
|
||||
@Parameter(description = "ID of book to retrieve", required = true)
|
||||
@PathVariable Long id
|
||||
) {
|
||||
return repository.findById(id)
|
||||
.orElseThrow(() -> new BookNotFoundException());
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Request Body Documentation
|
||||
```java
|
||||
import io.swagger.v3.oas.annotations.parameters.RequestBody;
|
||||
import io.swagger.v3.oas.annotations.media.ExampleObject;
|
||||
|
||||
@Operation(summary = "Create a new book")
|
||||
@ApiResponses(value = {
|
||||
@ApiResponse(
|
||||
responseCode = "201",
|
||||
description = "Book created successfully",
|
||||
content = @Content(
|
||||
mediaType = "application/json",
|
||||
schema = @Schema(implementation = Book.class)
|
||||
)
|
||||
),
|
||||
@ApiResponse(responseCode = "400", description = "Invalid input provided")
|
||||
})
|
||||
@PostMapping
|
||||
@ResponseStatus(HttpStatus.CREATED)
|
||||
public Book createBook(
|
||||
@RequestBody(
|
||||
description = "Book to create",
|
||||
required = true,
|
||||
content = @Content(
|
||||
mediaType = "application/json",
|
||||
schema = @Schema(implementation = Book.class),
|
||||
examples = @ExampleObject(
|
||||
value = """
|
||||
{
|
||||
"title": "Clean Code",
|
||||
"author": "Robert C. Martin",
|
||||
"isbn": "978-0132350884",
|
||||
"description": "A handbook of agile software craftsmanship"
|
||||
}
|
||||
"""
|
||||
)
|
||||
)
|
||||
)
|
||||
@org.springframework.web.bind.annotation.RequestBody Book book
|
||||
) {
|
||||
return repository.save(book);
|
||||
}
|
||||
```
|
||||
|
||||
## Model Documentation
|
||||
|
||||
### Entity with Validation Annotations
|
||||
```java
|
||||
import io.swagger.v3.oas.annotations.media.Schema;
|
||||
import jakarta.validation.constraints.*;
|
||||
|
||||
@Entity
|
||||
@Schema(description = "Book entity representing a published book")
|
||||
public class Book {
|
||||
|
||||
@Id
|
||||
@GeneratedValue(strategy = GenerationType.IDENTITY)
|
||||
@Schema(description = "Unique identifier", example = "1", accessMode = Schema.AccessMode.READ_ONLY)
|
||||
private Long id;
|
||||
|
||||
@NotBlank(message = "Title is required")
|
||||
@Size(min = 1, max = 200)
|
||||
@Schema(description = "Book title", example = "Clean Code", required = true, maxLength = 200)
|
||||
private String title;
|
||||
|
||||
@NotBlank(message = "Author is required")
|
||||
@Size(min = 1, max = 100)
|
||||
@Schema(description = "Book author", example = "Robert C. Martin", required = true)
|
||||
private String author;
|
||||
|
||||
@Pattern(regexp = "^(?:ISBN(?:-1[03])?:? )?(?=[0-9X]{10}$|(?=(?:[0-9]+[- ]){3})[- 0-9X]{13}$|97[89][0-9]{10}$|(?=(?:[0-9]+[- ]){4})[- 0-9]{17}$)(?:97[89][- ]?)?[0-9]{1,5}[- ]?[0-9]+[- ]?[0-9]+[- ]?[0-9X]$")
|
||||
@Schema(description = "ISBN number", example = "978-0132350884")
|
||||
private String isbn;
|
||||
|
||||
// Constructor, getters, setters
|
||||
}
|
||||
```
|
||||
|
||||
### Hidden Fields
|
||||
```java
|
||||
import com.fasterxml.jackson.annotation.JsonIgnore;
|
||||
import io.swagger.v3.oas.annotations.media.Schema;
|
||||
|
||||
@Schema(hidden = true)
|
||||
private String internalField;
|
||||
|
||||
@JsonIgnore
|
||||
@Schema(accessMode = Schema.AccessMode.READ_ONLY)
|
||||
private LocalDateTime createdAt;
|
||||
```
|
||||
|
||||
## Security Documentation
|
||||
|
||||
### JWT Bearer Authentication
|
||||
```java
|
||||
import io.swagger.v3.oas.annotations.security.SecurityRequirement;
|
||||
import io.swagger.v3.oas.models.Components;
|
||||
import io.swagger.v3.oas.models.security.SecurityScheme;
|
||||
|
||||
@Configuration
|
||||
public class OpenAPISecurityConfig {
|
||||
|
||||
@Bean
|
||||
public OpenAPI customOpenAPI() {
|
||||
return new OpenAPI()
|
||||
.components(new Components()
|
||||
.addSecuritySchemes("bearer-jwt", new SecurityScheme()
|
||||
.type(SecurityScheme.Type.HTTP)
|
||||
.scheme("bearer")
|
||||
.bearerFormat("JWT")
|
||||
.description("JWT authentication")
|
||||
)
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
// On controller or method level
|
||||
@SecurityRequirement(name = "bearer-jwt")
|
||||
@GetMapping("/secure")
|
||||
public String secureEndpoint() {
|
||||
return "Secure data";
|
||||
}
|
||||
```
|
||||
|
||||
### Basic Authentication
|
||||
```java
|
||||
@Bean
|
||||
public OpenAPI customOpenAPI() {
|
||||
return new OpenAPI()
|
||||
.components(new Components()
|
||||
.addSecuritySchemes("basicAuth", new SecurityScheme()
|
||||
.type(SecurityScheme.Type.HTTP)
|
||||
.scheme("basic")
|
||||
)
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### OAuth2 Configuration
|
||||
```java
|
||||
import io.swagger.v3.oas.models.security.OAuthFlow;
|
||||
import io.swagger.v3.oas.models.security.OAuthFlows;
|
||||
import io.swagger.v3.oas.models.security.Scopes;
|
||||
|
||||
@Bean
|
||||
public OpenAPI customOpenAPI() {
|
||||
return new OpenAPI()
|
||||
.components(new Components()
|
||||
.addSecuritySchemes("oauth2", new SecurityScheme()
|
||||
.type(SecurityScheme.Type.OAUTH2)
|
||||
.flows(new OAuthFlows()
|
||||
.authorizationCode(new OAuthFlow()
|
||||
.authorizationUrl("https://auth.example.com/oauth/authorize")
|
||||
.tokenUrl("https://auth.example.com/oauth/token")
|
||||
.scopes(new Scopes()
|
||||
.addString("read", "Read access")
|
||||
.addString("write", "Write access")
|
||||
)
|
||||
)
|
||||
)
|
||||
)
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### API Key Authentication
|
||||
```java
|
||||
@Bean
|
||||
public OpenAPI customOpenAPI() {
|
||||
return new OpenAPI()
|
||||
.components(new Components()
|
||||
.addSecuritySchemes("api-key", new SecurityScheme()
|
||||
.type(SecurityScheme.Type.APIKEY)
|
||||
.in(SecurityScheme.In.HEADER)
|
||||
.name("X-API-Key")
|
||||
)
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
## Pageable and Sorting Documentation
|
||||
|
||||
### Spring Data Pageable Support
|
||||
```java
|
||||
import org.springdoc.core.annotations.ParameterObject;
|
||||
import org.springframework.data.domain.Page;
|
||||
import org.springframework.data.domain.Pageable;
|
||||
|
||||
@Operation(summary = "Get paginated list of books")
|
||||
@GetMapping("/paginated")
|
||||
public Page<Book> findAllPaginated(
|
||||
@ParameterObject Pageable pageable
|
||||
) {
|
||||
return repository.findAll(pageable);
|
||||
}
|
||||
```
|
||||
|
||||
This automatically generates documentation for:
|
||||
- `page`: Page number (0-indexed)
|
||||
- `size`: Page size
|
||||
- `sort`: Sorting criteria (e.g., "title,asc")
|
||||
|
||||
## Advanced Features
|
||||
|
||||
### Multiple API Groups
|
||||
```java
|
||||
@Bean
|
||||
public GroupedOpenApi publicApi() {
|
||||
return GroupedOpenApi.builder()
|
||||
.group("public")
|
||||
.pathsToMatch("/api/public/**")
|
||||
.build();
|
||||
}
|
||||
|
||||
@Bean
|
||||
public GroupedOpenApi adminApi() {
|
||||
return GroupedOpenApi.builder()
|
||||
.group("admin")
|
||||
.pathsToMatch("/api/admin/**")
|
||||
.build();
|
||||
}
|
||||
```
|
||||
|
||||
Access groups at:
|
||||
- `/v3/api-docs/public`
|
||||
- `/v3/api-docs/admin`
|
||||
|
||||
### Hiding Endpoints
|
||||
```java
|
||||
@Operation(hidden = true)
|
||||
@GetMapping("/internal")
|
||||
public String internalEndpoint() {
|
||||
return "Hidden from docs";
|
||||
}
|
||||
|
||||
// Or hide entire controller
|
||||
@Hidden
|
||||
@RestController
|
||||
public class InternalController {
|
||||
// All endpoints hidden
|
||||
}
|
||||
```
|
||||
|
||||
### Custom Operation Customizer
|
||||
```java
|
||||
import org.springdoc.core.customizers.OperationCustomizer;
|
||||
|
||||
@Bean
|
||||
public OperationCustomizer customizeOperation() {
|
||||
return (operation, handlerMethod) -> {
|
||||
operation.addExtension("x-custom-field", "custom-value");
|
||||
return operation;
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### Filtering Packages and Paths
|
||||
```java
|
||||
@Bean
|
||||
public GroupedOpenApi apiGroup() {
|
||||
return GroupedOpenApi.builder()
|
||||
.group("api")
|
||||
.packagesToScan("com.example.controller")
|
||||
.pathsToMatch("/api/**")
|
||||
.pathsToExclude("/api/internal/**")
|
||||
.build();
|
||||
}
|
||||
```
|
||||
|
||||
## Kotlin Support
|
||||
|
||||
### Kotlin Data Class Documentation
|
||||
```kotlin
|
||||
import io.swagger.v3.oas.annotations.media.Schema
|
||||
import jakarta.validation.constraints.NotBlank
|
||||
import jakarta.validation.constraints.Size
|
||||
|
||||
@Entity
|
||||
data class Book(
|
||||
@field:Schema(description = "Unique identifier", accessMode = Schema.AccessMode.READ_ONLY)
|
||||
@Id
|
||||
val id: Long = 0,
|
||||
|
||||
@field:NotBlank
|
||||
@field:Size(min = 1, max = 200)
|
||||
@field:Schema(description = "Book title", example = "Clean Code", required = true)
|
||||
val title: String = "",
|
||||
|
||||
@field:NotBlank
|
||||
@field:Schema(description = "Author name", example = "Robert Martin")
|
||||
val author: String = ""
|
||||
)
|
||||
|
||||
@RestController
|
||||
@RequestMapping("/api/books")
|
||||
@Tag(name = "Book", description = "Book management APIs")
|
||||
class BookController(private val repository: BookRepository) {
|
||||
|
||||
@Operation(summary = "Get all books")
|
||||
@ApiResponses(value = [
|
||||
ApiResponse(
|
||||
responseCode = "200",
|
||||
description = "Found books",
|
||||
content = [Content(
|
||||
mediaType = "application/json",
|
||||
array = ArraySchema(schema = Schema(implementation = Book::class))
|
||||
)]
|
||||
),
|
||||
ApiResponse(responseCode = "404", description = "No books found", content = [Content()])
|
||||
])
|
||||
@GetMapping
|
||||
fun getAllBooks(): List<Book> = repository.findAll()
|
||||
}
|
||||
```
|
||||
|
||||
## Maven and Gradle Plugins
|
||||
|
||||
### Maven Plugin for Generating OpenAPI
|
||||
```xml
|
||||
<plugin>
|
||||
<groupId>org.springdoc</groupId>
|
||||
<artifactId>springdoc-openapi-maven-plugin</artifactId>
|
||||
<version>1.4</version>
|
||||
<executions>
|
||||
<execution>
|
||||
<phase>integration-test</phase>
|
||||
<goals>
|
||||
<goal>generate</goal>
|
||||
</goals>
|
||||
</execution>
|
||||
</executions>
|
||||
<configuration>
|
||||
<apiDocsUrl>http://localhost:8080/v3/api-docs</apiDocsUrl>
|
||||
<outputFileName>openapi.json</outputFileName>
|
||||
<outputDir>${project.build.directory}</outputDir>
|
||||
</configuration>
|
||||
</plugin>
|
||||
```
|
||||
|
||||
### Gradle Plugin
|
||||
```gradle
|
||||
plugins {
|
||||
id 'org.springdoc.openapi-gradle-plugin' version '1.9.0'
|
||||
}
|
||||
|
||||
openApi {
|
||||
apiDocsUrl = "http://localhost:8080/v3/api-docs"
|
||||
outputDir = file("$buildDir/docs")
|
||||
outputFileName = "openapi.json"
|
||||
}
|
||||
```
|
||||
|
||||
## Migration from SpringFox
|
||||
|
||||
Replace SpringFox dependencies and update annotations:
|
||||
- `@Api` → `@Tag`
|
||||
- `@ApiOperation` → `@Operation`
|
||||
- `@ApiParam` → `@Parameter`
|
||||
- Remove `Docket` beans, use `GroupedOpenApi` instead
|
||||
|
||||
## Common Issues and Solutions
|
||||
|
||||
### Parameter Names Not Appearing
|
||||
Add `-parameters` compiler flag (Spring Boot 3.2+):
|
||||
|
||||
```xml
|
||||
<plugin>
|
||||
<groupId>org.apache.maven.plugins</groupId>
|
||||
<artifactId>maven-compiler-plugin</artifactId>
|
||||
<configuration>
|
||||
<parameters>true</parameters>
|
||||
</configuration>
|
||||
</plugin>
|
||||
```
|
||||
|
||||
### Swagger UI Shows "Unable to render definition"
|
||||
Ensure `ByteArrayHttpMessageConverter` is registered when overriding converters:
|
||||
|
||||
```java
|
||||
converters.add(new ByteArrayHttpMessageConverter());
|
||||
converters.add(new MappingJackson2HttpMessageConverter());
|
||||
```
|
||||
|
||||
### Endpoints Not Appearing
|
||||
Check:
|
||||
- `springdoc.packages-to-scan` configuration
|
||||
- `springdoc.paths-to-match` configuration
|
||||
- Endpoints aren't marked with `@Hidden`
|
||||
|
||||
### Security Configuration Issues
|
||||
Permit SpringDoc endpoints in Spring Security:
|
||||
|
||||
```java
|
||||
@Bean
|
||||
public SecurityFilterChain filterChain(HttpSecurity http) {
|
||||
return http
|
||||
.authorizeHttpRequests(auth -> auth
|
||||
.requestMatchers("/v3/api-docs/**", "/swagger-ui/**", "/swagger-ui.html").permitAll()
|
||||
.anyRequest().authenticated()
|
||||
)
|
||||
.build();
|
||||
}
|
||||
```
|
||||
|
||||
## External References
|
||||
|
||||
- [SpringDoc Official Documentation](https://springdoc.org/)
|
||||
- [OpenAPI 3.0 Specification](https://swagger.io/specification/)
|
||||
- [Swagger UI Configuration](https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/)
|
||||
@@ -0,0 +1,247 @@
|
||||
# Troubleshooting SpringDoc OpenAPI
|
||||
|
||||
## Common Issues and Solutions
|
||||
|
||||
### Parameter Names Not Appearing
|
||||
|
||||
**Problem**: Parameter names are not showing up in the generated API documentation.
|
||||
|
||||
**Solution**: Add `-parameters` compiler flag (Spring Boot 3.2+):
|
||||
|
||||
```xml
|
||||
<plugin>
|
||||
<groupId>org.apache.maven.plugins</groupId>
|
||||
<artifactId>maven-compiler-plugin</artifactId>
|
||||
<configuration>
|
||||
<parameters>true</parameters>
|
||||
</configuration>
|
||||
</plugin>
|
||||
```
|
||||
|
||||
**Gradle equivalent**:
|
||||
```gradle
|
||||
tasks.withType(JavaCompile).configureEach {
|
||||
options.compilerArgs += ["-parameters"]
|
||||
}
|
||||
```
|
||||
|
||||
### Swagger UI Shows "Unable to render definition"
|
||||
|
||||
**Problem**: Swagger UI displays error "Unable to render definition".
|
||||
|
||||
**Solution**: Ensure `ByteArrayHttpMessageConverter` is registered when overriding converters:
|
||||
|
||||
```java
|
||||
converters.add(new ByteArrayHttpMessageConverter());
|
||||
converters.add(new MappingJackson2HttpMessageConverter());
|
||||
```
|
||||
|
||||
**Alternative approach**: Check for missing message converter configuration in your WebMvcConfigurer or similar configuration.
|
||||
|
||||
### Endpoints Not Appearing in Documentation
|
||||
|
||||
**Problem**: API endpoints are not showing up in the generated OpenAPI specification.
|
||||
|
||||
**Solution**: Check these common issues:
|
||||
|
||||
1. **Package scanning configuration**:
|
||||
```properties
|
||||
# Ensure this is set correctly
|
||||
springdoc.packages-to-scan=com.example.controller
|
||||
|
||||
# Or multiple packages
|
||||
springdoc.packages-to-scan=com.example.controller,com.example.service
|
||||
```
|
||||
|
||||
2. **Path matching configuration**:
|
||||
```properties
|
||||
# Ensure paths match your endpoints
|
||||
springdoc.paths-to-match=/api/**,public/**
|
||||
```
|
||||
|
||||
3. **Hidden endpoints**: Verify endpoints aren't marked with `@Hidden` annotation.
|
||||
|
||||
4. **Component scanning**: Ensure controllers are in packages that are component-scanned by Spring Boot.
|
||||
|
||||
### Security Configuration Issues
|
||||
|
||||
**Problem**: Spring Security blocks access to Swagger UI and OpenAPI endpoints.
|
||||
|
||||
**Solution**: Permit SpringDoc endpoints in Spring Security:
|
||||
|
||||
```java
|
||||
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
|
||||
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
|
||||
import org.springframework.security.web.SecurityFilterChain;
|
||||
|
||||
@Configuration
|
||||
@EnableWebSecurity
|
||||
public class SecurityConfig {
|
||||
|
||||
@Bean
|
||||
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
|
||||
return http
|
||||
.authorizeHttpRequests(auth -> auth
|
||||
.requestMatchers("/v3/api-docs/**", "/swagger-ui/**", "/swagger-ui.html").permitAll()
|
||||
.anyRequest().authenticated()
|
||||
)
|
||||
.build();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Maven/Gradle Build Issues
|
||||
|
||||
**Problem**: Build fails due to conflicting SpringDoc dependencies.
|
||||
|
||||
**Solution**: Ensure correct version compatibility:
|
||||
|
||||
```xml
|
||||
<dependency>
|
||||
<groupId>org.springdoc</groupId>
|
||||
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
|
||||
<version>2.8.13</version>
|
||||
</dependency>
|
||||
```
|
||||
|
||||
For WebFlux applications:
|
||||
```xml
|
||||
<dependency>
|
||||
<groupId>org.springdoc</groupId>
|
||||
<artifactId>springdoc-openapi-starter-webflux-ui</artifactId>
|
||||
<version>2.8.13</version>
|
||||
</dependency>
|
||||
```
|
||||
|
||||
### JavaDoc Integration Issues
|
||||
|
||||
**Problem**: JavaDoc comments are not appearing in the API documentation.
|
||||
|
||||
**Solution**: Add the therapi-runtime-javadoc dependency:
|
||||
|
||||
```xml
|
||||
<dependency>
|
||||
<groupId>com.github.therapi</groupId>
|
||||
<artifactId>therapi-runtime-javadoc</artifactId>
|
||||
<version>0.15.0</version>
|
||||
<scope>provided</scope>
|
||||
</dependency>
|
||||
```
|
||||
|
||||
### Kotlin Integration Issues
|
||||
|
||||
**Problem**: Kotlin classes or functions are not properly documented.
|
||||
|
||||
**Solution**: Use `@field:` annotation prefix for Kotlin properties:
|
||||
|
||||
```kotlin
|
||||
@field:Schema(description = "Book title", example = "Clean Code")
|
||||
@field:NotBlank
|
||||
val title: String = ""
|
||||
```
|
||||
|
||||
### Custom Serialization Issues
|
||||
|
||||
**Problem**: Custom serialized fields are not appearing in the API documentation.
|
||||
|
||||
**Solution**: Ensure proper Jackson configuration:
|
||||
|
||||
```java
|
||||
import com.fasterxml.jackson.databind.ObjectMapper;
|
||||
import org.springframework.context.annotation.Bean;
|
||||
import org.springframework.context.annotation.Configuration;
|
||||
|
||||
@Configuration
|
||||
public class JacksonConfig {
|
||||
|
||||
@Bean
|
||||
public ObjectMapper objectMapper() {
|
||||
return new ObjectMapper();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Performance Issues
|
||||
|
||||
**Problem**: SpringDoc causes performance issues during startup.
|
||||
|
||||
**Solution**:
|
||||
1. Use specific package scanning instead of scanning the entire classpath
|
||||
2. Use path exclusions to filter out unwanted endpoints
|
||||
3. Consider using grouped OpenAPI definitions
|
||||
|
||||
```java
|
||||
@Bean
|
||||
public GroupedOpenApi publicApi() {
|
||||
return GroupedOpenApi.builder()
|
||||
.group("public")
|
||||
.packagesToScan("com.example.controller.public")
|
||||
.pathsToMatch("/api/public/**")
|
||||
.pathsToExclude("/api/internal/**")
|
||||
.build();
|
||||
}
|
||||
```
|
||||
|
||||
### Version Compatibility Issues
|
||||
|
||||
**Problem**: SpringDoc works in development but not in production.
|
||||
|
||||
**Solution**:
|
||||
1. Ensure consistent Spring Boot and SpringDoc versions
|
||||
2. Check for environment-specific configurations
|
||||
3. Verify production environment matches development setup
|
||||
|
||||
```properties
|
||||
# Production-specific configuration
|
||||
springdoc.swagger-ui.enabled=true
|
||||
springdoc.api-docs.enabled=true
|
||||
springdoc.show-actuator=true
|
||||
```
|
||||
|
||||
### Error Response Documentation
|
||||
|
||||
**Problem**: Custom error responses are not properly documented.
|
||||
|
||||
**Solution**: Use `@Operation(hidden = true)` on exception handlers and define proper error response schemas:
|
||||
|
||||
```java
|
||||
@ExceptionHandler(BookNotFoundException.class)
|
||||
@ResponseStatus(HttpStatus.NOT_FOUND)
|
||||
@Operation(hidden = true)
|
||||
public ErrorResponse handleBookNotFound(BookNotFoundException ex) {
|
||||
return new ErrorResponse("BOOK_NOT_FOUND", ex.getMessage());
|
||||
}
|
||||
|
||||
@Schema(description = "Error response")
|
||||
public record ErrorResponse(
|
||||
@Schema(description = "Error code", example = "BOOK_NOT_FOUND")
|
||||
String code,
|
||||
|
||||
@Schema(description = "Error message", example = "Book with ID 123 not found")
|
||||
String message
|
||||
) {}
|
||||
```
|
||||
|
||||
### Debugging Tips
|
||||
|
||||
1. **Check OpenAPI JSON directly**: Access `http://localhost:8080/v3/api-docs` to see the raw OpenAPI specification
|
||||
2. **Enable debug logging**: Add `logging.level.org.springdoc=DEBUG` to application.properties
|
||||
3. **Validate OpenAPI specification**: Use online validators like [Swagger Editor](https://editor.swagger.io/)
|
||||
4. **Check SpringDoc version**: Ensure you're using a recent version with bug fixes
|
||||
|
||||
### Performance Optimization
|
||||
|
||||
1. **Reduce scope**: Use specific package scanning and path matching
|
||||
2. **Cache configurations**: Reuse OpenAPI configurations where possible
|
||||
3. **Group endpoints**: Use multiple grouped OpenAPI definitions instead of one large specification
|
||||
4. **Disable unnecessary features**: Turn off features you don't use (e.g., actuator integration)
|
||||
|
||||
```properties
|
||||
# Performance optimizations
|
||||
springdoc.swagger-ui.enabled=true
|
||||
springdoc.api-docs.enabled=true
|
||||
springdoc.show-actuator=false
|
||||
springdoc.writer-default-response-tags=false
|
||||
springdoc.default-consumes-media-type=application/json
|
||||
springdoc.default-produces-media-type=application/json
|
||||
```
|
||||
Reference in New Issue
Block a user