문제점

스웨거 UI 접근 시 500 에러가 발생한다. 서버 로그에서는 No static resource v3/api-docs 메시지가 표시된다.
서버 내부에서는 정상적으로 실행되지만 외부에서 스웨거 UI 접근 시 문제가 발생하고 있다.

원인 분석

• 스웨거 API 문서 경로가 올바르게 설정되지 않음
• 스프링독(SpringDoc) 설정이 불완전함
• @OpenAPIDefinition 어노테이션과 서버 URL 설정 누락

SwaggerConfig

@Configuration
@OpenAPIDefinition(
    info = @Info(
        title = "FreeMarket API",
        description = "FreeMarket 프로젝트 API 문서",
        version = "v1.0.0",
        contact = @Contact(
            name = "FreeMarket",
            email = "rlaxogjs202014030@gmail.com",
            url = "http://localhost:8080"
        )
    ),
    servers = {
        @io.swagger.v3.oas.annotations.servers.Server(url = "https://freemarket.duckdns.org", description = "Production Server"),
        @io.swagger.v3.oas.annotations.servers.Server(url = "http://localhost:8080", description = "Development Server")
    }
)
public class SwaggerConfig {

    @Bean
    public OpenAPI openAPI() {
        final String securitySchemeName = "bearerAuth";

        return new OpenAPI()
                .info(new io.swagger.v3.oas.models.info.Info()
                        .title("FreeMarket API")
                        .description("FreeMarket 프로젝트 API 문서")
                        .version("v1.0.0")
                        .contact(new io.swagger.v3.oas.models.info.Contact()
                                .name("FreeMarket")
                                .email("rlaxogjs202014030@gmail.com")
                                .url("http://localhost:8080"))
                )
                .servers(List.of(
                        new Server().url("https://freemarket.duckdns.org").description("Production Server"),
                        new Server().url("http://localhost:8080").description("Development Server")
                ))
                .addSecurityItem(new SecurityRequirement().addList(securitySchemeName))
                .components(new Components()
                        .addSecuritySchemes(securitySchemeName, new SecurityScheme()
                                .name(securitySchemeName)
                                .type(SecurityScheme.Type.HTTP)
                                .scheme("bearer")
                                .bearerFormat("JWT")));
    }

    @Bean
    public GroupedOpenApi publicApi() {
        return GroupedOpenApi.builder()
                .group("public")
                .pathsToMatch("/api/**")
                .build();
    }
}

• Swagger 메타정보 등록 (@OpenAPIDefinition)
• OpenAPI 객체를 수동으로 생성 (@Bean)
• 특정 경로만 문서화 하도록 그룹 설정 (/api/**만 Swagger에 노출)
• servers: 테스트 가능한 서버 목록

Yml

springdoc:
  api-docs:
    path: /v3/api-docs
    enabled: true
  swagger-ui:
    path: /swagger-ui.html
    enabled: true

• springdoc.api-docs.path: /v3/api-docs
  - OpenAPI 문서를 JSON 형식으로 반환하는 엔드포인트 경로
  - 기본값은 /v3/api-docs이지만, 변경도 가능
  - 브라우저에서 https://your-domain.com/v3/api-docs 로 접근하면 OpenAPI JSON이 나와야 Swagger UI가 동작

• springdoc.api-docs.enabled: true
  - OpenAPI 문서(JSON)를 생성할지 여부를 설정
  - false로 설정하면 /v3/api-docs가 아예 비활성화
  - Swagger UI는 이 문서를 기반으로 하기 때문에, 꺼져 있으면 UI도 작동 안 함

CORS

        // 스웨거 UI 경로에 대한 CORS 설정 추가
        registry.addMapping("/swagger-ui/**")
                .allowedOrigins("*") // 또는 특정 도메인
                .allowedMethods("GET", "POST", "OPTIONS")
                .allowedHeaders("*")
                .maxAge(3600);