swagger-stylelisted

The house style for springdoc-openapi annotations on a Spring REST controller and its DTOs - `@Operation`, `@ApiResponses`, `@Parameter`, `@Schema`, `@ParameterObject`. Load it before adding or changing `io.swagger.v3.oas.annotations` on a controller, a record or an enum, when a new endpoint is added to an annotated controller, when checking `/v3/api-docs` or Swagger UI against the code, and when Swagger UI documents an error as returning the success body, shows a `@ModelAttribute` filter as one object parameter, asks for a parameter the server fills in itself, answers 415 on a multipart "Try it out", or drops enum descriptions. Not for javadoc (the separate `javadoc-style` skill), and not for designing paths, statuses or error responses - those are the `controller-style` and `controller-advice-style` skills, taken as given here.
dmitriy-iliyov/java-agent-skills · ★ 0 · API & Backend · score 72

Install: claude install-skill dmitriy-iliyov/java-agent-skills

# Swagger style House rules for springdoc-openapi annotations on a REST controller and its DTOs. An annotation that breaks one of them is either wrong, or a reason to change the rule here deliberately. Every string in an annotation is English. The annotations document decisions made elsewhere and make none of their own: paths, verbs, statuses and whether `@ResponseStatus` is written at all follow the `controller-style` skill ([../controller-style/SKILL.md](../controller-style/SKILL.md)); which errors an endpoint answers and what an error response carries follow the `controller-advice-style` skill ([../controller-advice-style/SKILL.md](../controller-advice-style/SKILL.md)). ## What gets annotated | Where | What it carries | |---|---| | **Endpoint method** | `@Operation(summary = ...)` and `@ApiResponses` - see [Responses](#responses) for which codes | | **Path variable, query parameter** | `@Parameter(description = ...)`; a path variable also `required = true` | | **Request / response record** | `@Schema(description = ...)` on the type and on every component - see [Fields](#fields) | | **Enum used in a request or response** | `@Schema(description = ..., enumAsRef = true)` on the type, nothing on the constants - see [Fields](#fields) | | **Query parameters bound through `@ModelAttribute`** | `@ParameterObject` on the method parameter - see [Traps](#traps) | | **Type from a module without a springdoc dependency** | nothing, referenced through `implementation` - its fields sh