프로젝트 #1 스프링부트 SpringBoot 3x Swagger 적용법

회사 동료들이랑 프로젝트 시작!

개발 환경은 Spring Boot X React로

오랜만에 스프링부트 환경 세팅 중.

다음 회의 까지 각자 맡은 기능 api 정리하기로 해서

스웨거를 적용해보았다.

 

Swagger란

REST API 웹 서비스를 설계, 빌드, 문서화해주는 오픈 소스 소프트웨어 프레임워크.
API 명세, 관리, 테스트 가능

 

SpringBoot Swagger 적용법

스프링부트 스웨거 라이브러리는 springfox, springdoc 2가지가 대표적인 것 같았는데

나는 springdoc을 적용했다.

 

1. 의존성

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

 

2. SwaggerConfig.java

스웨거 설정 정보 작성할 클래스 생성

import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI openAPI(){

        return new OpenAPI()
                .components(new Components())
                .info(apiInfo());
    }

    private Info apiInfo() {

        return new Info()
                .title("Perfing 프로젝트 API")
                .description("사이트 성능 지표 측정 및 실시간 채팅")
                .version("1.0.0");
    }
}

 

3.Swagger UI 사이트 접속

http://서버 포트 번호/swagger-ui/index.html#/

 

위 주소로 처음 접속 시 아래 화면이 뜬다.

에러가 나서 고생했다는 글이 많던데 나는 한 번에 접속 가능했다.ㅎㅎ 휴...

 

모든 설정을 마치고 다시 접속하면 아래와 같이 내가 Config 파일에서 작성한 설명글이 뜬다!

 

4. application.yml 작성

yml 작성은 필수는 아닌 듯하다.

좀더 공부해봐야겠다.

 

5. Annotaion

Swaager 2와 Swagger 3의 어노테이션이 많이 다르므로 주의해서 사용해야 한다.

Swagger 3 annotaions	desc
@Tag	클래스를 Swagger 리소스로 표시
@Paremeter(hidden = true) or @Opertaion(hidden = true) or @Hidden	API 작업 시 단일 매개 변수를 나타냄
@Parameter	API 작업 시 단일 매개 변수를 나타냄
@Parameters	API 작업 시 복수 매개 변수를 나타냄
@Schema	Swagger 모델에 대한 추가 정보 제공
@Schema(accessMode = READ_ONLY)	모델 속성의 데이터를 추가하고 조작
@Operation(summary = "foo", description = "bar")	특정 경로에 대한 작업 또는 일반적으로 HTTP 메서드 설명
@Parameter	작업 매개 변수에 대한 추가 메타 데이터 추가
@ApiResponse(responseCode = "404", description = "foo")	작업의 가능한 응답 설명

 

 

내가 맡은 기능은 실시간 채팅 기능이라 샘플 ChatController 작성 후 어노테이션을 적용해보았다.

 

컨트롤러에 작성한대로 Swagger-UI에 잘 나오는 것을 확인할 수 있다!