spring-boot-openapi-documentation

Q: How do I install spring-boot-openapi-documentation?

Run npx skills add https://github.com/giuseppe-trisciuoglio/developer-kit --skill spring-boot-openapi-documentation in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/spring-boot-openapi-documentation/ (personal) or .claude/skills/spring-boot-openapi-documentation/ (project).

Q: Which AI agents can use spring-boot-openapi-documentation?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Q: Is spring-boot-openapi-documentation safe to install?

Security partners have reviewed it: Gen Agent Trust Hub passed; Socket passed; Snyk passed; Runlayer flagged items to review; ZeroLeaks passed. As with any skill, read the SKILL.md and bundled scripts before installing.

Q: Who maintains spring-boot-openapi-documentation?

It is published by giuseppe-trisciuoglio in giuseppe-trisciuoglio/developer-kit. It has 4,036 recorded installs.

by giuseppe-trisciuoglioBackend & APIs

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.

Installs: 4K
Last 24h: —
Trending rank: —
Security: Warn

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/giuseppe-trisciuoglio/developer-kit --skill spring-boot-openapi-documentation

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads spring-boot-openapi-documentation automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

Security audits

Independent scans of the skill's instructions and bundled files.

Gen Agent Trust Hub PassSAFE ·The skill provides standard configuration instructions and best practices for setting up SpringDoc OpenAPI 3.0 and Swagger UI in Spring Boot 3.x applications. No malicious patterns, obfuscation, or data exfiltration practices were found.

Socket PassNo alerts

Snyk PassLOW ·Risk: LOW · No issues

Runlayer WarnMEDIUM ·3/3 files flagged

ZeroLeaks PassNONE ·Score: 93/100 · 2 sections analyzed

SKILL.md

The instructions your agent reads when the skill is triggered.

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

Concept	Description
Dependencies	`springdoc-openapi-starter-webmvc-ui` for WebMvc, `springdoc-openapi-starter-webflux-ui` for WebFlux
Configuration	`application.yml` with `springdoc.api-docs.` and `springdoc.swagger-ui.` properties
Access Points	OpenAPI JSON: `/v3/api-docs`, Swagger UI: `/swagger-ui/index.html`
Core Annotations	`@Tag`, `@Operation`, `@ApiResponse`, `@Parameter`, `@Schema`, `@SecurityRequirement`
Security	Configure security schemes in OpenAPI bean, apply with `@SecurityRequirement`
Pagination	Use `@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:

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:

@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:

@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:

@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:

@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 — Maven/Gradle dependencies and version selection
configuration.md — Basic and advanced configuration options
controller-documentation.md — Controller and endpoint documentation patterns
model-documentation.md — Entity, DTO, and validation documentation
security-configuration.md — JWT, OAuth2, Basic Auth, API key configuration
pagination-support.md — Pageable, Slice, and custom pagination patterns
advanced-configuration.md — API groups, customizers, OpenAPI bean configuration
exception-handling.md — Exception documentation and error response schemas
build-integration.md — Maven/Gradle plugins and CI/CD integration
complete-examples.md — Full controller, entity, and configuration examples
annotations-reference.md — Complete annotation reference with attributes
springdoc-official.md — Official SpringDoc documentation
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

@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

@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

@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

FAQ

What does the spring-boot-openapi-documentation skill do?

How do I install spring-boot-openapi-documentation?

Run npx skills add https://github.com/giuseppe-trisciuoglio/developer-kit --skill spring-boot-openapi-documentation in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/spring-boot-openapi-documentation/ (personal) or .claude/skills/spring-boot-openapi-documentation/ (project).

Which AI agents can use spring-boot-openapi-documentation?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is spring-boot-openapi-documentation safe to install?

Security partners have reviewed it: Gen Agent Trust Hub passed; Socket passed; Snyk passed; Runlayer flagged items to review; ZeroLeaks passed. As with any skill, read the SKILL.md and bundled scripts before installing.

Who maintains spring-boot-openapi-documentation?

It is published by giuseppe-trisciuoglio in giuseppe-trisciuoglio/developer-kit. It has 4,036 recorded installs.