giuseppe-trisciuoglio/developer-kit

spring-boot-openapi-documentation

Provides patterns to generate comprehensive REST API documentation using SpringDoc OpenAPI 3.0 and Swagger UI in Spring Boot 3.x applications.

소스 보기

사용 방법

  1. 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
  2. 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
  3. 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
npx skills add https://github.com/giuseppe-trisciuoglio/developer-kit --skill spring-boot-openapi-documentation

시작 전 확인

  • 설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
  • 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 Skill 문서

원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.

Spring Boot OpenAPI Documentation with SpringDoc

Overview

SpringDoc OpenAPI automates generation of OpenAPI 3.0 documentation for Spring Boot projects with a Swagger UI web interface for exploring and testing APIs.

When to Use

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

Quick Reference

ConceptDescription
Dependenciesspringdoc-openapi-starter-webmvc-ui for WebMvc, springdoc-openapi-starter-webflux-ui for WebFlux
Configurationapplication.yml with springdoc.api-docs.* and springdoc.swagger-ui.* properties
Access PointsOpenAPI JSON: /v3/api-docs, Swagger UI: /swagger-ui/index.html
Core Annotations@Tag, @Operation, @ApiResponse, @Parameter, @Schema, @SecurityRequirement
SecurityConfigure security schemes in OpenAPI bean, apply with @SecurityRequirement
PaginationUse @ParameterObject with Spring Data Pageable

Instructions

1. Add Dependencies

Add SpringDoc starter for your application type (WebMvc or WebFlux). See dependency-setup.md for Maven/Gradle configuration.

2. Configure SpringDoc

Set basic configuration in application.yml:

yaml
springdoc:
  api-docs:
    path: /api-docs
  swagger-ui:
    path: /swagger-ui.html
    operationsSorter: method

See configuration.md for advanced options.

3. Document Controllers

Use OpenAPI annotations to add descriptive information:

java
@RestController
@Tag(name = "Book", description = "Book management APIs")
public class BookController {

    @Operation(summary = "Get book by ID")
    @ApiResponse(responseCode = "200", description = "Book found")
    @GetMapping("/{id}")
    public Book findById(@PathVariable Long id) { }
}

See controller-documentation.md for patterns.

4. Document Models

Apply @Schema annotations to DTOs:

java
@Schema(description = "Book entity")
public class Book {
    @Schema(example = "1", accessMode = Schema.AccessMode.READ_ONLY)
    private Long id;

    @Schema(example = "Clean Code", required = true)
    private String title;
}

See model-documentation.md for validation patterns.

5. Configure Security

Set up security schemes in OpenAPI bean:

java
@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
        .components(new Components()
            .addSecuritySchemes("bearer-jwt", new SecurityScheme()
                .type(SecurityScheme.Type.HTTP)
                .scheme("bearer")
                .bearerFormat("JWT")
            )
        );
}

Apply with @SecurityRequirement(name = "bearer-jwt") on controllers. See security-configuration.md.

6. Document Pagination

Use @ParameterObject for Spring Data Pageable:

java
@GetMapping("/paginated")
public Page<Book> findAll(@ParameterObject Pageable pageable) {
    return repository.findAll(pageable);
}

See pagination-support.md.

7. Test Documentation

Access Swagger UI at /swagger-ui/index.html to verify documentation completeness.

8. Customize for Production

Configure API grouping, versioning, and build plugins. See advanced-configuration.md and build-integration.md.

Best Practices

  • Use descriptive operation summaries: Short (< 120 chars), clear statements
  • Document all response codes: Include success (2xx), client errors (4xx), server errors (5xx)
  • Add examples to request/response bodies: Use @ExampleObject for realistic examples
  • Leverage JSR-303 validation annotations: SpringDoc auto-generates constraints from validation annotations
  • Use `@ParameterObject` for complex parameters: Especially for Pageable, custom filter objects
  • Group related endpoints with `@Tag`: Organize API by domain entities or features
  • Document security requirements: Apply @SecurityRequirement where authentication needed
  • Hide internal endpoints appropriately: Use @Hidden or create separate API groups
  • Customize Swagger UI for better UX: Enable filtering, sorting, try-it-out features
  • Version your API documentation: Include version in OpenAPI Info

References

  • [dependency-setup.md](references/dependency-setup.md) — Maven/Gradle dependencies and version selection
  • [configuration.md](references/configuration.md) — Basic and advanced configuration options
  • [controller-documentation.md](references/controller-documentation.md) — Controller and endpoint documentation patterns
  • [model-documentation.md](references/model-documentation.md) — Entity, DTO, and validation documentation
  • [security-configuration.md](references/security-configuration.md) — JWT, OAuth2, Basic Auth, API key configuration
  • [pagination-support.md](references/pagination-support.md) — Pageable, Slice, and custom pagination patterns
  • [advanced-configuration.md](references/advanced-configuration.md) — API groups, customizers, OpenAPI bean configuration
  • [exception-handling.md](references/exception-handling.md) — Exception documentation and error response schemas
  • [build-integration.md](references/build-integration.md) — Maven/Gradle plugins and CI/CD integration
  • [complete-examples.md](references/complete-examples.md) — Full controller, entity, and configuration examples
  • [annotations-reference.md](references/annotations-reference.md) — Complete annotation reference with attributes
  • [springdoc-official.md](references/springdoc-official.md) — Official SpringDoc documentation
  • [troubleshooting.md](references/troubleshooting.md) — Common issues and solutions

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

Examples

Basic Controller Documentation

java
@RestController
@Tag(name = "Books", description = "Book management APIs")
@RequestMapping("/api/books")
public class BookController {

    @Operation(
        summary = "Get book by ID",
        description = "Retrieves detailed information about a specific book"
    )
    @ApiResponse(responseCode = "200", description = "Book found")
    @ApiResponse(responseCode = "404", description = "Book not found")
    @GetMapping("/{id}")
    public Book getBook(@PathVariable Long id) {
        return bookService.findById(id);
    }

    @Operation(summary = "Create new book")
    @SecurityRequirement(name = "bearer-jwt")
    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)
    public Book createBook(@Valid @RequestBody CreateBookRequest request) {
        return bookService.create(request);
    }
}

Documented Model with Validation

java
@Schema(description = "Book entity")
public class Book {
    @Schema(description = "Unique identifier", example = "1", accessMode = Schema.AccessMode.READ_ONLY)
    private Long id;

    @Schema(description = "Book title", example = "Clean Code", required = true)
    @NotBlank
    @Size(min = 1, max = 200)
    private String title;

    @Schema(description = "Author name", example = "Robert C. Martin")
    @NotBlank
    private String author;

    @Schema(description = "Price in USD", example = "29.99", minimum = "0")
    @NotNull
    @DecimalMin("0.0")
    private BigDecimal price;
}

Security Configuration

java
@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
        .info(new Info()
            .title("Book API")
            .version("1.0.0")
            .description("REST API for book management"))
        .components(new Components()
            .addSecuritySchemes("bearer-jwt", new SecurityScheme()
                .type(SecurityScheme.Type.HTTP)
                .scheme("bearer")
                .bearerFormat("JWT"))
            .addSecuritySchemes("api-key", new SecurityScheme()
                .type(SecurityScheme.Type.APIKEY)
                .in(SecurityScheme.In.HEADER)
                .name("X-API-Key")));
}

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

External Resources

관련 작업

같은 저장소의 Skills

더 많은 Skills

모든 Skills
giuseppe-trisciuoglio
커뮤니티

drizzle-orm-patterns

Provides comprehensive Drizzle ORM patterns for schema definition, CRUD operations, relations, queries, transactions, and migrations. Proactively use for any Drizzle ORM development including defining database schemas, writing type-safe queries, implementing relations, managing transactions, and setting up migrations with Drizzle Kit. Supports PostgreSQL, MySQL, SQLite, MSSQL, and CockroachDB.

1시간 설치 수
3
GitHub Stars
372
업데이트
9월 10일
giuseppe-trisciuoglio
커뮤니티

tailwind-css-patterns

Provides comprehensive Tailwind CSS utility-first styling patterns including responsive design, layout utilities, flexbox, grid, spacing, typography, colors, and modern CSS best practices. Use when styling React/Vue/Svelte components, building responsive layouts, implementing design systems, or optimizing CSS workflow.

1시간 설치 수
1
GitHub Stars
372
업데이트
9월 10일
giuseppe-trisciuoglio
커뮤니티

dynamodb-toolbox-patterns

Provides TypeScript patterns for DynamoDB-Toolbox v2 including schema/table/entity modeling, .build() command workflow, query/scan access patterns, batch and transaction operations, and single-table design with computed keys. Use when implementing type-safe DynamoDB access layers with DynamoDB-Toolbox v2 in TypeScript services or serverless applications.

1시간 설치 수
1
GitHub Stars
371
업데이트
9월 10일
giuseppe-trisciuoglio
커뮤니티

spring-boot-dependency-injection

Provides dependency injection patterns for Spring Boot projects, including constructor-first design, optional collaborator handling, bean selection, and wiring validation. Use when creating services and configurations, replacing field injection, or troubleshooting ambiguous or fragile Spring wiring.

1시간 설치 수
1
GitHub Stars
371
업데이트
9월 10일