> 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)
curl "https://skillshub.wtf/HoangNguyen0403/agent-skills-standard/spring-boot-api-design?format=md"Spring Boot API Design Standards
Priority: P0
Implementation Guidelines
OpenAPI (Swagger)
- SpringDoc: Use
springdoc-openapi-starter-webmvc-ui. - Annotations: Use
@Operationand@ApiResponse. Keep clean. - Schema: Define examples in
@Schemaon 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
ProblemDetailwith 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
> related_skills --same-repo
> typescript-tooling
Development tools, linting, and build config for TypeScript. Use when configuring ESLint, Prettier, Jest, Vitest, tsconfig, or any TS build tooling. (triggers: tsconfig.json, .eslintrc.*, jest.config.*, package.json, eslint, prettier, jest, vitest, build, compile, lint)
> typescript-security
Secure coding practices for TypeScript. Use when validating input, handling auth tokens, sanitizing data, or managing secrets and sensitive configuration. (triggers: **/*.ts, **/*.tsx, validate, sanitize, xss, injection, auth, password, secret, token)
> typescript-language
Modern TypeScript standards for type safety and maintainability. Use when working with types, interfaces, generics, enums, unions, or tsconfig settings. (triggers: **/*.ts, **/*.tsx, tsconfig.json, type, interface, generic, enum, union, intersection, readonly, const, namespace)
> typescript-best-practices
Idiomatic TypeScript patterns for clean, maintainable code. Use when writing or refactoring TypeScript classes, functions, modules, or async logic. (triggers: **/*.ts, **/*.tsx, class, function, module, import, export, async, promise)