---
name: swagger-api-docs-creator
description: Create or refactor Swagger/OpenAPI documentation for Spring MVC controllers by moving long method-level Swagger annotations into reusable meta-annotations under each domain's controller.swagger package. Use when requests mention documenting controllers, cleaning up Swagger annotations, converting inline Swagger docs into meta-annotations, or adding Korean Swagger descriptions and examples. Example triggers include "ContentController API를 Swagger로 문서화해줘", "컨트롤러 Swagger 문서를 메타 어노테이션으로 정리해줘", and "OpenAPI 문서를 한국어로 추가해줘".
---

# Swagger API Docs Creator

## Overview

Document Spring MVC controllers with Swagger/OpenAPI while keeping controllers readable.

Move long method-level Swagger annotations into domain-specific meta-annotations so controller methods keep only routing, status code, service calls, and a single documentation annotation.

## Workflow

1. Inspect the target controllers and list their endpoints.
2. Inspect request DTOs, response DTOs, common error responses, and security behavior.
3. Create or update a `controller.swagger` package for each domain.
4. Create one method-level meta-annotation per endpoint.
5. Replace inline Swagger blocks on controller methods with the new meta-annotations.
6. Keep DTO field schemas in DTO classes when they improve response clarity.
7. For endpoints handled directly by Spring Security, avoid fake runtime controllers and document them from `OpenApiConfiguration` instead.
8. Verify compilation and tests after the refactor.

## Rules

- Place meta-annotations under `src/main/java/<domain>/controller/swagger/`.
- Use `@Target(ElementType.METHOD)` and `@Retention(RetentionPolicy.RUNTIME)` for method documentation annotations.
- Use a separate parameter-level meta-annotation when internal parameters such as `@AuthenticationPrincipal` must be hidden.
- Keep class-level shared annotations such as `@Tag` and `@SecurityRequirement` on the controller.
- Move method-level `@Operation`, `@ApiResponses`, and `@Parameters` into meta-annotations.
- Treat list responses as arrays. Use `@ArraySchema` and provide array-shaped JSON examples.
- Write generated Swagger summaries, descriptions, response descriptions, and examples in Korean and save those source files as UTF-8.
- Keep examples faithful to the real response shape. If a method returns `List`, the example must be a JSON array.
- Prefer documenting login endpoints handled by Spring Security in `OpenApiConfiguration` instead of introducing a controller that never serves runtime traffic.

## Example Pattern

```java
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
@Operation(summary = "<Korean summary>", description = "<Korean description>")
@Parameters({
        @Parameter(name = "cursorId", description = "<Korean parameter description>", example = "10"),
        @Parameter(name = "cursorDate", description = "<Korean parameter description>", example = "2026-03-29T09:00:00Z"),
        @Parameter(name = "size", description = "<Korean parameter description>", example = "10")
})
@ApiResponses({
        @ApiResponse(
                responseCode = "200",
                description = "<Korean success description>",
                content = @Content(
                        mediaType = MediaType.APPLICATION_JSON_VALUE,
                        array = @ArraySchema(schema = @Schema(implementation = ContentResponse.class))
                )
        )
})
public @interface FindAllContentsApi {
}
```

```java
@GetMapping
@ResponseStatus(HttpStatus.OK)
@FindAllContentsApi
public List<ContentResponse> findAll(
        @RequestParam(required = false) Long cursorId,
        @RequestParam(required = false) Instant cursorDate,
        @RequestParam int size) {
    return contentService.findAll(cursorId, cursorDate, size);
}
```

## Validation

- Check that Swagger UI and `/v3/api-docs` remain accessible when expected.
- Check that security-handled endpoints are documented without changing runtime routing.
- Run the project's standard compile or test command.
- If terminal output looks garbled on Windows, reopen files with explicit UTF-8 decoding before assuming the source itself is broken.