Spring - Swagger UI 적용하기

배경

프로젝트 고도화를 진행하며 프론트와 협업을 시작하며 RESTful API를 시각화하여 공유하기 위해 적용했다.

 

Swagger UI

시각적 문서화

• Swagger UI는 API의 구조를 시각적으로 표시
• 개발자가 API의 리소스, 메소드, 파라미터 등을 쉽게 이해할 수 있게 해줌

상호작용 가능한 API 탐색

• 사용자는 API 엔드포인트에 대한 요청을 직접 실행하고, 응답을 받아 볼 수 있음
• API의 실제 동작을 테스트하고 탐색할 수 있음

쉬운 통합

• Swagger UI는 OpenAPI 사양을 기반으로 작동
• OpenAPI를 지원하는 언어나 프레임워크로 작성된 API와 쉽게 통합할 수 있음

---

1. Swagger UI 접속 관련 설정

실습에서 사용한 SpringBoot 버전

plugins {
    id 'java'
    id 'org.springframework.boot' version '3.2.1'
    id 'io.spring.dependency-management' version '1.1.4'
}

 

Swagger의 버전은 3.X.X 를 사용한다

API Test를 위해 접속해야 하는 URL : 서버주소/swagger-ui/index.html

---

2. 구현

사용하기 위한 의존성

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.2.0'

 

Spring Security

.permitAll()
	.requestMatchers("/swagger-ui/**")
	.permitAll();

 

Application.yml

springdoc: 
  swagger-ui: 
    groups-order: desc 
    tags-sorter: alpha 
    operations-sorter: method 
    disable-swagger-default-url: true 
    display-request-duration: true 
    default-models-expand-depth: 2
    default-model-expand-depth: 2
    
  api-docs: # API 문서 관련 설정을 정의합니다.
    path: /api-docs # API 문서의 경로를 설정합니다. 
    
  show-actuator: true  
  default-consumes-media-type: application/json 
  default-produces-media-type: application/json  
  writer-with-default-pretty-printer: true 
  model-and-view-allowed: true  
  paths-to-match:
    - /api/**

 

Swagger UI 설정

• 그룹 정렬: API 그룹을 내림차순(desc)으로 정렬하여 가장 최근 혹은 중요한 그룹을 상단에 표시
• 태그 정렬: API 태그를 알파벳 순(alpha)으로 정렬하여 문서의 탐색성을 향상
• 연산 정렬: API 연산을 HTTP 메소드의 알파벳 순으로 정렬하여 문서의 일관성을 유지
• 기본 URL 비활성화: Swagger UI 로딩 시 제공되는 기본 URL을 비활성화하여 사용자 정의 문서를 우선적으로 표시
• 요청 실행 시간 표시: API 요청의 실행 시간을 표시하여 성능 분석을 용이하게 함
• 모델 확장 깊이 설정: 모델을 기본적으로 2단계 깊이까지 펼쳐 보여줌

API 문서 설정

• 문서 경로 설정: API 문서의 경로를 /api-docs로 설정하여 접근성을 향상시킵니다.

추가 설정

• Spring Boot Actuator 엔드포인트 표시: API 문서에 Actuator 엔드포인트를 표시하여 관리 및 모니터링 기능을 강화
• 미디어 타입 설정: 기본 소비 및 생성 미디어 타입을 application/json으로 설정하여 API와의 상호 작용을 명확히 함
• JSON 응답 예쁘게 출력: JSON 응답을 들여쓰기 등을 통해 가독성 있게 출력
• ModelAndView 허용: Spring MVC의 ModelAndView 객체를 API 응답으로 허용하여 뷰와 모델 데이터의 결합을 가능하게 해줌
• 문서화할 경로 설정: /api/** 경로로 시작하는 모든 엔드포인트를 문서화 대상으로 지정

 

SwaggerConfig

• JWT 사용하지 않는 경우

@Configuration
public class SwaggerConfig {
    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                .components(new Components())
                .info(apiInfo());
    }

    private Info apiInfo() {
        return new Info()
                .title("API Test") // API의 제목
                .description("Swagger UI for Img_Forest") // API에 대한 설명
                .version("1.0.0"); // API의 버전
    }
}

• JWT 사용하는 경우

@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI openAPI() {
        String jwt = "JWT";
        // SecurityRequirement 객체 생성 및 JWT를 인증 범위에 추가
        SecurityRequirement securityRequirement = new SecurityRequirement().addList(jwt);
        // 보안 스킴 초기화 및 설정
        Components components = new Components().addSecuritySchemes(jwt, new SecurityScheme()
                        .name(jwt)
                        .type(SecurityScheme.Type.HTTP)
                        .scheme("bearer")
                        .bearerFormat("JWT")
                );

        // OpenAPI 객체 생성 및 정보 설정
        return new OpenAPI()
                .components(new Components())
                .info(apiInfo())
                .addSecurityItem(securityRequirement)
                .components(components);
    }


    // API 기본 정보 제공 메소드
    private Info apiInfo() {
        return new Info()
                .title("API Test")
                .description("Swagger UI for Img_Forest")
                .version("1.0.0");
    }
}

 

 

골라서 작성 후 서버 접속

• 서버주소/swagger-ui/index.html

 

API 설정 관련 어노테이션

@Tag나 @Operation, @ApiResponses 같은 어노테이션으로 API에 대한 설명할 수 있음

 

@Tag

@RestController
@RequiredArgsConstructor
@RequestMapping("/api/member")
@Tag(name = "Member", description = "Member API")
public class MemberController {
...
}

 

@Operation

 @PostMapping("/signup")
    @Operation(summary = "회원가입", description = "회원가입 시 사용하는 API")
    public GlobalResponse signup(@RequestBody MemberCreateRequestDto userCreateRequestDto) {
    ...
    }

 

@ApiResponses

@ApiResponses(value = {
        @ApiResponse(responseCode = "200", description = "요청에 성공하였습니다.", content = @Content(mediaType = "application/json")),
        @ApiResponse(responseCode = "400", description = "요청에 실패했습니다.", content = @Content(mediaType = "application/json")),
        @ApiResponse(responseCode = "401", description = "인증이 필요합니다.", content = @Content(mediaType = "application/json")),
        @ApiResponse(responseCode = "403", description = "요청이 거부되었습니다.", content = @Content(mediaType = "application/json")),
        @ApiResponse(responseCode = "404", description = "리소스를 서버에서 찾을 수 없습니다.", content = @Content(mediaType = "application/json"))
})
public class MemberController {
...
}

 

@Parameters

@Parameters({
        @Parameter(name = "email", description = "이메일", example = "chrome123@naver.com"),
        @Parameter(name = "password", description = "6자~12자 이내", example = "pw1234"),
        @Parameter(name = "companyName", description = "업체명", example = "Img_Forest"),
        @Parameter(name = "companyNumber", description = "업체 번호", example = "123456"),
        @Parameter(name = "companyAddress", description = "업체 주소", example = "OO시 OO구 OO동")
})

 

최종

 

 

참고 블로그

https://velog.io/@gmlstjq123/SpringBoot-%ED%94%84%EB%A1%9C%EC%A0%9D%ED%8A%B8%EC%97%90-Swagger-UI-%EC%A0%81%EC%9A%A9%ED%95%98%EA%B8%B0

SpringBoot 프로젝트에 Swagger UI 적용하기