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

@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 {
}

@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.