[Springboot][Backend] Swagger 연동해서 백엔드 API Docs 자동화하기

Swagger 란?

 

Swagger는 서비스 명세(ex: Rest API)를 쉽게 문서화해주는 오픈 소스 프레임워크입니다. 각각의 API가 어떤 로직을 수행하며, 어떤 값(parameter)을 요청하고, 응답값(response)는 무엇인지를 자동으로 정리하여 문서화해주는 기능을 수행합니다. 

 

프론트엔드와 백엔드가 협업하여 개발을 진행해야 할 때, 백엔드가 개발한 내용을 Swagger를 이용해서 API Docs 형태로 전달하면, 서로 효율적으로 협업을 진행할 수 있습니다.

 

Swagger로 만든 API Docs 기본

 

 

적용 방법

 

Springboot backend를 개발하는 경우, External library에 Swagger를 추가해주는 방식으로 기본적인 적용이 가능합니다. 이 때 유의해야 할 사항은, Springboot 버전에 적합한 종속성을 추가해주어야 합니다.

 

Springboot 3.x.x 버전의 경우 Springfox가 아닌, Springdocs로 종속성을 추가하도록 합니다.

저의 프로젝트의 경우엔 Springboot 3.4.1을 사용하고 있기 때문에, 아래와 같이 dependency를 추가합니다.

 

# build.gradle

dependencies {
    // Spring 3.4.1과 호환되는 Swagger 버전
    implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.7.0'
}

 

자신이 사용하는 Springboot 버전에 맞는 버전을 사용하지 않으면, 정상작동이 되지 않으므로 주의하여야 합니다.

선택적으로,  API docs의 제목과 설명을 붙이고 싶다면 아래의 Config file을 추가할 수 있습니다.

 

@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("Sample API")
                        .version("1.0.0")
                        .description("This is a sample Swagger OpenAPI configuration."));
    }
}

 

이와 같이 적용이 끝나면, 백엔드를 로컬에서 수행한 후, 아래의 경로에 접근하여 API Docs를 확인할 수 있습니다.

- Swagger UI: http://localhost:8080/swagger-ui/index.html
- OpenAPI JSON: http://localhost:8080/v3/api-docs

 

협업을 위해 공유하기

 

API Docs 생성을 마친 후, API 가이드를 공유하기 위한 여러가지 방법들이 있습니다. 그 중 가장 간단하게 html 파일을 작성하여 공유하는 방법이 있습니다. 일단 OpenAPI JSON 경로로 접근하여, 해당 JSON의 모든 내용을 복사한 후, 아래 사이트에 접속하면 JSON을 API Docs 형태로 바꿔줍니다.

 

Swagger Editor

Swagger Editor

 

JSON을 좌측에 붙여넣기한 후, 상단 메뉴의 Generate client > html2 를 누르면 자동으로 html2 파일이 압축파일로 다운로드되며, 압축을 해제하여 나온 html파일을 배포하면 끝입니다. 

 

 

오늘은 간단하게 Swagger를 적용하고 API문서를 작성하고, 배포하는 방법에 대해 알아보았습니다.  끝!