Agent-Skills.md

Agent Skills: Spring Boot API Design Standards

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. (triggers: **/*Controller.java, openapi, swagger, versioning, problemdetails)

UncategorizedID: hoangnguyen0403/agent-skills-standard/spring-boot-api-design

Repository

hoangnguyen0403/agent-skills-standard
HoangNguyen0403License: Apache-2.0
362103

Install this agent skill to your local

pnpm dlx add-skill https://github.com/HoangNguyen0403/agent-skills-standard/tree/HEAD/skills/spring-boot/spring-boot-api-design

Skill Files

Browse the full folder contents for spring-boot-api-design.

Download Skill

Loading file tree…

skills/spring-boot/spring-boot-api-design/SKILL.md

Skill Metadata

Name
spring-boot-api-design
Description
"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. (triggers: **/*Controller.java, 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

  • 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