OpenSkillIndex← back to search
claude-code

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

install
source · Clone the upstream repo
git clone https://github.com/ComeOnOliver/skillshub
Claude Code · Install into ~/.claude/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/ComeOnOliver/skillshub "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/HoangNguyen0403/agent-skills-standard/spring-boot-api-design" ~/.claude/skills/comeonoliver-skillshub-spring-boot-api-design && rm -rf "$T"
manifest: skills/HoangNguyen0403/agent-skills-standard/spring-boot-api-design/SKILL.md
source content

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