Profile My skills Saved My plugins Edit profile Submit a skill

Spring Boot API Design

Design Spring Boot APIs with OpenAPI, Versioning, and Global Error Handling. Use when designing Spring Boot APIs with OpenAPI specs, versioning, or global error handling.

HoangNguyen0403 Updated 542 repo stars
Integrations & APIs

File contents

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

  • Implementation Examples

HoangNguyen0403/agent-skills-standard/tree/main/skills/spring-boot/spring-boot-api-design commit f40fdc62df

Browse category

Frequently asked questions

npx skillmds@latest add hoangnguyen0403/spring-boot-api-design