giuseppe-trisciuoglio/developer-kit

Comprehensive developer toolkit providing reusable skills for Java/Spring Boot, TypeScript/NestJS/React/Next.js, Python, PHP, AWS CloudFormation, AI/RAG, DevOps, and more.

Quality

82%

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Risky

Do not use without reviewing

Validation failed for skills in this tile

One or more skills have errors that need to be fixed before they can move to Implementation and Discovery review.

name:: spring-boot-openapi-documentation
description:: Provides patterns to 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, Edit, Bash, Glob, Grep

Spring Boot OpenAPI Documentation with SpringDoc

Name: giuseppe-trisciuoglio/developer-kit
Rating: 82.6470588235294 (1 reviews)
Author: giuseppe-trisciuoglio

Overview

SpringDoc OpenAPI is a library that automates the generation of OpenAPI 3.0 documentation for Spring Boot projects. It provides a Swagger UI web interface for exploring and testing APIs without writing additional configuration. This skill provides comprehensive patterns for integrating SpringDoc into Spring Boot 3.x applications, documenting REST endpoints, securing API documentation, and customizing the generated specification.

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

Instructions

Follow these steps to implement comprehensive API documentation with SpringDoc OpenAPI:

1. Add Dependencies and Configure

Add the appropriate SpringDoc starter dependency for your application type (WebMvc or WebFlux) and configure basic settings in application.yml or application.properties.

2. Document Controllers

Use OpenAPI annotations (@Tag, @Operation, @ApiResponse, @Parameter) to add descriptive information to your REST controllers. Group related endpoints under tags and document all response codes.

3. Document Models

Apply @Schema annotations to DTOs and entities to document field constraints, examples, and validation rules. Hide internal fields and mark read-only properties appropriately.

4. Configure Security

Set up security schemes for authentication methods (JWT Bearer, OAuth2, Basic Auth) and apply @SecurityRequirement to protected endpoints.

5. Test Documentation

Access Swagger UI at /swagger-ui/index.html to verify documentation completeness. Test endpoints directly from the UI to ensure examples are accurate.

6. Customize for Production

Configure API grouping, versioning, and customize UI appearance. Set up build plugins to generate OpenAPI JSON/YAML files during the build process.

7. Integrate with CI/CD

Add API documentation generation to your build pipeline and consider automated contract testing.

Setup Dependencies

Add Maven Dependencies

<!-- 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

// 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

# 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/**

# 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

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

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

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

@Schema(hidden = true)
private String internalField;

@JsonIgnore
@Schema(accessMode = Schema.AccessMode.READ_ONLY)
private LocalDateTime createdAt;

Document Security

JWT Bearer Authentication

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

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

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

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

import org.springdoc.core.customizers.OperationCustomizer;

@Bean
public OperationCustomizer customizeOperation() {
    return (operation, handlerMethod) -> {
        operation.addExtension("x-custom-field", "custom-value");
        return operation;
    };
}

Hide Endpoints

@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

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

<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

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

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

Use descriptive operation summaries and descriptions
- Summary: Short, clear statement (< 120 chars)
- Description: Detailed explanation with use cases
Document all response codes
- Include success (2xx), client errors (4xx), server errors (5xx)
- Provide meaningful descriptions for each
Add examples to request/response bodies
- Use @ExampleObject for realistic examples
- Include edge cases when relevant
Leverage JSR-303 validation annotations
- SpringDoc auto-generates constraints from validation annotations
- Reduces duplication between code and documentation
Use @ParameterObject for complex parameters
- Especially useful for Pageable, custom filter objects
- Keeps controller methods clean
Group related endpoints with @Tag
- Organize API by domain entities or features
- Use consistent tag names across controllers
Document security requirements
- Apply @SecurityRequirement where authentication needed
- Configure security schemes globally in OpenAPI bean
Hide internal/admin endpoints appropriately
- Use @Hidden or create separate API groups
- Prevent exposing internal implementation details
Customize Swagger UI for better UX
- Enable filtering, sorting, try-it-out features
- Set appropriate default behaviors
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

Constraints and Warnings

Do not expose sensitive data in API examples or schema descriptions.
Keep OpenAPI annotations minimal to avoid cluttering controller code; use global configurations when possible.
Large API definitions can impact Swagger UI performance; consider grouping APIs by domain.
Schema generation may not work correctly with complex generic types; use explicit @Schema annotations.
Avoid circular references in DTOs as they cause infinite recursion in schema generation.
Security schemes must be properly configured before using @SecurityRequirement annotations.
Hidden endpoints (@Operation(hidden = true)) are still visible in code and may leak through other documentation tools.

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

plugins

developer-kit-aws

developer-kit-core

developer-kit-java

skills

aws-lambda-java-integration

aws-rds-spring-boot-integration

aws-sdk-java-v2-bedrock

aws-sdk-java-v2-core

aws-sdk-java-v2-dynamodb

aws-sdk-java-v2-kms

aws-sdk-java-v2-lambda

aws-sdk-java-v2-messaging

aws-sdk-java-v2-rds

aws-sdk-java-v2-s3

aws-sdk-java-v2-secrets-manager

graalvm-native-image

langchain4j

langchain4j-ai-services-patterns

langchain4j-mcp-server-patterns

langchain4j-rag-implementation-patterns

langchain4j-spring-boot-integration

langchain4j-testing-strategies

langchain4j-tool-function-calling-patterns

langchain4j-vector-stores-configuration

qdrant

spring-ai-mcp-server-patterns

spring-boot-actuator

spring-boot-cache

spring-boot-crud-patterns

spring-boot-dependency-injection

spring-boot-event-driven-patterns

spring-boot-openapi-documentation

references

SKILL.md

spring-boot-project-creator

spring-boot-resilience4j

spring-boot-rest-api-standards

spring-boot-saga-pattern

spring-boot-test-patterns

spring-data-jpa

spring-data-neo4j

unit-test-application-events

unit-test-bean-validation

unit-test-boundary-conditions

unit-test-caching

unit-test-config-properties

unit-test-controller-layer

unit-test-exception-handler

unit-test-json-serialization

unit-test-mapper-converter

unit-test-parameterized

unit-test-scheduled-async

unit-test-security-authorization

unit-test-service-layer

unit-test-utility-methods

unit-test-wiremock-rest-api

wiremock-standalone-docker

developer-kit-php

developer-kit-python

developer-kit-tools

developer-kit-typescript

README.md

tile.json

giuseppe-trisciuoglio/developer-kit

SKILL.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}plugins/developer-kit-java/skills/spring-boot-openapi-documentation/

Spring Boot OpenAPI Documentation with SpringDoc

Overview

When to Use

Instructions

1. Add Dependencies and Configure

2. Document Controllers

3. Document Models

4. Configure Security

5. Test Documentation

6. Customize for Production

7. Integrate with CI/CD

Setup Dependencies

Add Maven Dependencies

Add Gradle Dependencies

Configure SpringDoc

Basic Configuration

Access Endpoints

Document Controllers

Basic Controller Documentation

Document Request Bodies

Document Models

Entity with Validation

Hidden Fields

Document Security

JWT Bearer Authentication

OAuth2 Configuration

Document Pagination

Spring Data Pageable Support

Advanced Configuration

Multiple API Groups

Custom Operation Customizer

Hide Endpoints

Document Exception Responses

Global Exception Handler

Build Integration

Maven Plugin

Gradle Plugin

Examples

Complete REST Controller Example

Best Practices

Common Annotations Reference

Core Annotations

Validation Annotations (Auto-documented)

Troubleshooting

Constraints and Warnings

Related Skills

References

SKILL.mdplugins/developer-kit-java/skills/spring-boot-openapi-documentation/