playbooks

home / skills / hoangnguyen0403 / agent-skills-standard / api-design

api-design skill

/skills/spring-boot/api-design

This skill helps you design Spring Boot APIs with OpenAPI, URI versioning, and robust RFC 7807 error handling.

npx playbooks add skill hoangnguyen0403/agent-skills-standard --skill api-design

Review the files below or copy the command above to add this skill to your agents.

Files (2)
SKILL.md
1.2 KB
---
name: Spring Boot API Design
description: Standards for OpenAPI, Versioning, and Global Error Handling
metadata:
  labels: [spring-boot, api, openapi, swagger]
  triggers:
    files: ['**/*Controller.java']
    keywords: [openapi, swagger, versioning, problemdetails]
---

# Spring Boot API Design Standards

## **Priority: P0**

## Implementation Guidelines

### OpenAPI (Swagger)

- **SpringDoc**: Use `springdoc-openapi-starter-webmvc-ui`.
- **Annotations**: Use `@Operation` and `@ApiResponse`. Keep clean.
- **Schema**: Define examples in `@Schema` on DTOs.

### API Versioning

- **Strategy**: Prefer **URI Versioning** (`/api/v1/`) for caching simplicity.
- **Deprecation**: Use `@Deprecated` + OpenAPI flag.

### Error Handling (RFC 7807)

- **ProblemDetails**: Enable `spring.mvc.problem-details.enabled=true`.
- **Extension**: Extend `ProblemDetail` with custom fields if needed.
- **Security**: NEVER expose stack traces in API errors.

## Anti-Patterns

- **Untyped Response**: `**No Map<K,V>**: Return typed DTOs.`
- **Header Versioning**: `**No Headers**: Hard to test/cache.`
- **Undocumented**: `**No hidden APIs**: Use Swagger.`

## References

- [Implementation Examples](references/implementation.md)

Overview

This skill codifies Spring Boot API design standards focused on OpenAPI, versioning, and global error handling. It provides concrete rules and examples to produce discoverable, versioned, and secure REST APIs that integrate cleanly with SpringDoc and RFC 7807 ProblemDetails. The goal is consistent API behavior, better client caching, and safer error responses.

How this skill works

The skill prescribes using springdoc-openapi starter for automatic Swagger UI and annotation-driven documentation with @Operation, @ApiResponse, and @Schema examples on DTOs. It favors URI-based API versioning (e.g., /api/v1/) for caching and clarity, and mandates deprecation signals via @Deprecated plus OpenAPI flags. For errors it enables spring.mvc.problem-details and extends ProblemDetail for custom fields while preventing leakage of stack traces.

When to use it

  • When building or refactoring Spring Boot REST endpoints that need discoverable API docs.
  • When you require stable, cache-friendly versioning across clients and proxies.
  • When you need standardized, machine-readable error responses conforming to RFC 7807.
  • When you want to prevent insecure or undocumented endpoints from reaching production.
  • When team-wide consistency on DTO typing and API contracts is required.

Best practices

  • Use springdoc-openapi-starter-webmvc-ui and annotate controllers with @Operation and @ApiResponse.
  • Define examples and types on DTOs using @Schema to ensure typed, self-describing responses.
  • Prefer URI versioning like /api/v1/ for caching simplicity and clear client routing.
  • Mark deprecated versions with @Deprecated and an OpenAPI deprecation flag; provide migration notes.
  • Enable spring.mvc.problem-details.enabled=true and extend ProblemDetail for safe custom fields.
  • Never expose stack traces or internal diagnostics in API error payloads or logs returned to clients.

Example use cases

  • Expose a public REST API with Swagger UI and explicit DTO examples for third-party integrators.
  • Migrate from v1 to v2 of an API while keeping /api/v1/ endpoints live and clearly marked as deprecated.
  • Standardize error responses across microservices using extended ProblemDetail objects.
  • Audit an existing codebase to replace Map responses with typed DTOs and add OpenAPI annotations.
  • Reject header-based versioning during design reviews in favor of URI versioning for cacheability.

FAQ

Why prefer URI versioning over header versioning?

URI versioning is simpler for caching, routing, and testing. Header versioning hides the version from caches and can complicate client and proxy behavior.

How do I add custom fields to ProblemDetails safely?

Extend ProblemDetail with explicit fields, serialize only non-sensitive data, and avoid including stack traces or internal identifiers visible to clients.

Are DTO examples required in @Schema?

Yes. Examples improve API discoverability and make generated docs and client code clearer for integrators.