# Spring Boot API Design

> Standards for OpenAPI, Versioning, and Global Error Handling

- Skill: `fierzone/spring-boot-api-design` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add fierzone/spring-boot-api-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/fierzone/spring-boot-api-design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: fierzone (https://skillmd.com/u/fierzone)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/fierzone/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

- **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)