SpringBoot3.x.x Swagger 적용하기

스웨거(Swagger)는 RESTful API를 설계, 빌드, 문서화, 테스트하는 데 사용되는 오픈 소스 프레임워크입니다. 현재는 OpenAPI Specification(OAS)이라는 이름으로 발전했으며, 스웨거는 이 표준을 구현한 가장 널리 사용되는 도구 중 하나입니다.

주요 기능:

• API 문서화: 코드에서 주석이나 설정을 기반으로 API 명세서를 자동으로 생성합니다.
• Swagger UI: 브라우저 기반의 인터페이스를 제공하여 개발자나 사용자들이 API의 구조를 시각적으로 확인하고 테스트할 수 있도록 합니다.
• 테스트 및 시뮬레이션: API 호출을 시뮬레이션하여 동작을 검증할 수 있습니다.

장점:

• 자동 문서화: 개발자의 코드와 문서화를 동기화시켜 API 변경 시 문서도 자동으로 업데이트됩니다.
• 실시간 테스트: Swagger UI를 통해 사용자는 API를 바로 테스트할 수 있어 개발 및 디버깅이 용이합니다.
• 표준화: OpenAPI Specification을 기반으로 하여 API 문서를 표준화된 포맷으로 제공합니다.

 

라이브러리 추가

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

 

Swagger Config 작성

package com.sparta.codechef.config;

import io.swagger.v3.oas.models.info.Info; // Swagger API 문서 정보를 설정하기 위한 import
import io.swagger.v3.oas.models.security.SecurityScheme; // 보안 스키마를 설정하기 위한 import
import io.swagger.v3.oas.models.Components; // 보안 컴포넌트 정의를 위한 import
import io.swagger.v3.oas.models.OpenAPI; // OpenAPI 설정을 위한 import
import io.swagger.v3.oas.models.security.SecurityRequirement; // 보안 요구 사항 설정을 위한 import
import org.springframework.context.annotation.Bean; // 스프링 빈 등록을 위한 import
import org.springframework.context.annotation.Configuration; // 설정 클래스 지정 import

@Configuration // 이 클래스가 설정 파일임을 나타냅니다.
public class SwaggerConfig {

    // OpenAPI 설정을 Bean으로 등록하여 스프링 컨텍스트에 제공
    @Bean
    public OpenAPI openAPI() {
        String jwt = "JWT"; // 보안 스키마의 이름 지정

        // 보안 요구 사항 생성: Swagger UI에서 인증 토큰이 필요함을 나타냄
        SecurityRequirement securityRequirement = new SecurityRequirement().addList(jwt);

        // 보안 스키마 설정: JWT 토큰 사용을 위한 'bearer' 스키마 정의
        Components components = new Components().addSecuritySchemes(jwt, new SecurityScheme()
                .name(jwt) // 보안 스키마의 이름
                .type(SecurityScheme.Type.HTTP) // HTTP 타입의 보안 스키마
                .scheme("bearer") // 'bearer' 인증 타입 사용
                .bearerFormat("JWT") // 형식은 JWT
        );

        // OpenAPI 객체를 생성하여 구성 요소와 보안 설정을 추가
        return new OpenAPI()
                .components(new Components()) // 빈 컴포넌트 추가 (중복 방지를 위해 수정 가능)
                .info(apiInfo()) // API 문서의 기본 정보 추가
                .addSecurityItem(securityRequirement) // 보안 요구 사항 추가
                .components(components); // 보안 스키마가 포함된 컴포넌트 추가
    }

    // API 문서의 기본 정보를 설정하는 메서드
    private Info apiInfo() {
        return new Info()
                .title("API Test") // API 문서의 제목 설정
                .description("Let's practice Swagger UI") // API 설명
                .version("1.0.0"); // API 버전
    }
}

 

 yml 선택사항

springdoc:
  swagger-ui:
    path: /api-test  # swagger-ui 접근 경로에 대한 별칭, 해당 주소로 접속해도 http://localhost:8080/swagger-ui/index.html로 리다이렉션 됨.

    groups-order: DESC # path, query, body, response 순으로 출력

    tags-sorter: alpha # 태그를 알파벳 순으로 정렬

    operations-sorter: method  # delete - get - patch - post - put 순으로 정렬, alpha를 사용하면 알파벳 순으로 정렬 가능

  paths-to-match:
    - /api/** # swagger-ui에 표시할 api의 엔드포인트 패턴

 

 

설정을 마치고 http://localhost:8080/swagger-ui/index.html << 들어가면 

 

드디어 Swagger Ui에 들어왔습니다.

그리고 만약에 스프링시큐리티가 적용되어 있다면 

.requestMatchers("/v3/api-docs/**","/swagger-ui/**","/api-test"

추가 하셔야만 입장이 가능합니다!!

로그인 url을 펼치고 오른쪽 상단에 Try it out 클릭하시면 됩니다.

 

 

해당 값을 넣고 Execute를 클릭하면

 

 

성공과 함께 토큰이 반환 됩니다. 이 토큰을을 Bearer빼고 뒷부븐만 복사한뒤

(예시로 위에 반환된 토큰에 eyJhbGciOiJIUzM4NCJ9.eyJjYXRlZ29yeSI6IkFDQ0VTUyIsImV4cCI6MTczMDczMDAxMiwic3ViIjoiNiIsImVtYWlsIjoidGVzdDVAbmF2ZXIuY29tIiwidXNlclJvbGUiOiJST0xFX0FETUlOIiwiaWF0IjoxNzMwNzE1NjEyfQ.DG3EIO8EvaBVSCaoi-zj5J0QISq_Dj3Ad46b2UBBO0hZcwWcF5q6lO1OcQyP2cIW 만 복사면 됩니다.)

아까 첫번째 이미지 오른쪽 상단 보면 자물쇠가 있습니다. 

클릭하시면 이렇게 토큰 넣는 창이 나오고 Authorize버튼을 누르면 전체 메소드 헤더에 토큰값이 들어가게 됩니다.

값을 넣으면 

자물쇠가 잠기게 됩니다 만약 모든 메서드에 필요하지 않고 일부에만 필요하다면 오른쯕 상단에 좌물쇠가 아니라 메서드에 있는 자물쇠 하나를 클릭해서 넣어주시면 메서드 별로 토큰 설정이 가능합니다^^

 

결론

스웨거(Swagger)는 RESTful API를 설계하고 문서화하는 데 있어 강력한 도구입니다. 특히 OpenAPI Specification을 기반으로 API 명세서를 자동으로 생성하고, Swagger UI를 통해 API 문서를 시각적으로 제공하며, 개발자와 사용자 모두 쉽게 API를 테스트할 수 있도록 지원합니다.

스프링 부트 프로젝트에서 springdoc-openapi를 사용하여 간편하게 Swagger 설정을 추가할 수 있으며, 보안 설정을 통해 JWT와 같은 인증 스키마를 포함할 수도 있습니다. 이를 통해 보안이 적용된 환경에서도 Swagger UI를 통해 인증된 API 테스트를 할 수 있습니다.

스프링 시큐리티가 적용된 경우, 특정 경로에 대한 접근 권한을 허용하는 설정이 필요하며, 이를 통해 개발자는 보안된 API 문서를 안전하게 테스트할 수 있습니다. Swagger UI에서 제공하는 Try it out 기능과 Authorize 버튼을 통해 JWT 토큰을 설정하면 각 API 요청에 자동으로 인증 헤더가 추가되어 테스트할 수 있습니다.

결국, 스웨거는 API 문서화를 효율적이고 표준화된 방식으로 지원하여 개발 및 협업의 생산성을 높이는 데 기여합니다. 이 설정과 기능을 통해 더욱 직관적이고 강력한 API 개발 환경을 구축할 수 있습니다.