[Spring] Swagger UI

yee·2024년 10월 5일

목록 보기

3/6

🎈 Swagger UI

: Swagger UI는 프론트엔드와 백엔드의 협업에 사용되는 툴.

별도의 코드 추가 없이도 OpenAPI 규격에 맞게 API 를 자동으로 시각화 시켜줌

API 명세서를 직접 작성할 필요가 없어지므로, API의 유지보수가 간단해진다

🎈 Swagger UI 설정

1) 실습에서 사용하는 Spring Boot 버전 (gradle)

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

2) API Test를 위해 접속해야 하는 URL

localhost:8080/swagger-ui/index.html

3) Swagger 문서 생성 시 사용되는 라이브러리 (Springfox vs Springdoc)

: Spring 기반 애플리케이션에서 Swagger 문서를 생성할 때 사용하는 라이브러리에는 Springfox와 Springdoc이 있는데, 최신 개발 환경에 더 적합한 것은 Springdoc이다. => Springdoc 사용

build.gradle 파일에 아래의 의존성을 추가한다.

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

4) SwaggerConfig 클래스를 생성하고, 아래의 코드를 입력한다.

i) jwt를 사용하는 경우

import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.security.SecurityRequirement;
import io.swagger.v3.oas.models.security.SecurityScheme;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration    //Spring은 이 클래스를 감지하고 정의한 Bean을 애플리케이션 컨텍스트에 등록
public class SwaggerConfig {
    @Bean
    public OpenAPI openAPI(){
        String jwt="JWT"; //API 요청을 인증하고 허가하는 데 널리 사용되는 보안 체계 이름
        return new OpenAPI()  //API의 구조, 메타데이터, 구성 요소 및 보안 요구 사항을 정의하는 데 사용
                .components(new Components())  //API에 기본 구성 요소가 추가되어 보안 체계와 같은 재사용 가능한 부분을 구성할 수 있습니다.
                .info(apiInfo())   //제목, 설명, 버전과 같은 API에 대한 메타데이터를 제공
                .addSecurityItem(new SecurityRequirement().addList(jwt)) //API가 클라이언트가 인증을 위해 JWT 토큰을 보내도록 요구한다는 것을 지정
                .components(new Components().addSecuritySchemes(jwt,new SecurityScheme()
                        .name(jwt)
                        .type(SecurityScheme.Type.HTTP)
                        .scheme("bearer")
                        .bearerFormat("JWT"))
                );
    }
    private Info apiInfo(){
        return new Info()
                .title("Test API")
                .description("This is Swagger UI.")
                .version("1.0.0");
    }
}

ii) 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("Let's practice Swagger UI") // API에 대한 설명
                .version("1.0.0"); // API의 버전
    }
}

5) application.yml 파일에 추가적인 설정 (필수적이지는 x)

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의 엔드포인트 패턴