Spring Boot API Design Standards
Priority: P0 (CRITICAL)
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 hard to test/cache.
- No hidden APIs: Document all endpoints with Swagger/OpenAPI.
References
