# Spring Boot API Design

> Standards for OpenAPI, Versioning, and Global Error Handling. Use when designing Spring Boot APIs with OpenAPI specs, versioning, or global error handling. (triggers: **/*Controller.java, openapi, swagger, versioning, problemdetails)

- Skill: `comeonoliver/spring-boot-api-design` (Agent Skill)
- Install (CLI): `npx skillmds@latest add comeonoliver/spring-boot-api-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/comeonoliver/spring-boot-api-design/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: ComeOnOliver (https://skillmd.com/u/comeonoliver)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/comeonoliver/spring-boot-api-design

---


# 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

- **No Map<K,V> responses**: Return typed DTO records instead.
- **No Header Versioning**: Use URI versioning; headers are hard to test/cache.
- **No hidden APIs**: Document all endpoints with Swagger/OpenAPI.

## References

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