[Spring] Swagger 사용방법에 대해 간단하게.araboza

개요

백엔드 개발자는 여러 프로젝트를 진행을 하면서 프론트엔드 개발자 혹은 PM등 여러 사람과 같이 협업을 진행을 하게 된다.

그럴 때 API 개요, 설명, 사용방법, 전달해야되는 데이터 등에 대해서 설명을 해주어야한다.

그래서 API Docs을 정리를 해둔다. 여러가지 API 문서를 정리해주는 툴이 있다.

 

대표적으로 아래와 같이 있다.

• gitBook
• Spring REST Docs
• Swagger

하지만 이번에 알아볼 Swagger는 API를 자동으로 문서화를 진행을 해준다.

가장 이번에는 간단하게 적용만 하는 방법에 대해서 알아볼 것이다.

 

 

설치 과정

0. 블로그 주인장 진행 환경

• ubuntu 22.04 LTS
• Intellj IDEA Ultimate Edition 2024.3.1.1
• openJDK 21.0.2
• SpringBoot 3.4.1

 

1. build.gradle

dependencies {

	/* 생략 */

	//Swagger
    implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.2'
}

 

위의 의존성을 추가를 해주어야 Swagger 사용이 가능하다.

springdoc-openai 말고 spring-fox를 사용하는 경우도 있는데, 블로그 주인장 같은 경우는 위의 것으로 진행을 하였으니 설명은

위의 의존성으로 설명을 하도록 하겠다.

 

 

2. Application 설정

.properties

springdoc.version=V.0.0.1
springdoc.swagger-ui.path=/swagger.html
springdoc.swagger-ui.tags-sorter=alpha
springdoc.swagger-ui.operations-sorter=alpha
springdoc.api-docs.path=/api-docs

springdoc.default-consumes-media-type=application/json;charset=UTF-8
springdoc.default-produces-media-type=application/json;charset=UTF-8

 

 

.yml

springdoc:
  version: V.0.0.1
  swagger-ui:
    path: /swagger.html
    tags-sorter: alpha
  api-docs:
    path: /api-docs
  default-consumes-media-type: application/json;charset=UTF-8
  default-produces-media-type: application/json;charset=UTF-8

 

 

사용하는 것중 하나로 설정하자.

 

3. OpenApiConfig

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.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiConfig {
    @Bean
    public OpenAPI openAPI(@Value("${springdoc.version}") String springdocVersion) {
        Info info = new Info()
                .title("제목")
                .version(springdocVersion)
                .description("설명");

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

 

 

 

springdoc.version 은 application 에서 설정한 Version을 따라간다.

 

"제목"이라고 적힌 곳은 API문서 제목을 뜻하고

"설명"은 swagger-ui에 들어가면 밑에 어떤 API 문서인지 설명을 적는 것이다.

 

나머지는 OpenAPI가 알아서 진행을 해준다.

 

4. TestController

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@Tag(name = "Test", description = "Test API")
@RestController
public class TestController {

    @Operation(
            summary = "Test method",
            description = "This is test method",
            responses = {
                    @ApiResponse(
                            responseCode = "200",
                            description = "Test success"
                    ),
                    @ApiResponse(
                            responseCode = "400",
                            description = "Test failed"
                    )
            }
    )
    @GetMapping("/test")
    public String getTest() {
        return "Test success";
    }
}

 

태그	속성	설명
@Tag		Controller에 대한 설명을 명시하는 어노테이션
@Tag	name	API 그룹의 이름을 지정하는 속성
@Tag	description	API 그룹의 설명을 지정하는 속성
@Operation		API 그룹 내에 각각의 API를 명시하는 어노테이션
@Operation	summary	API에 대한 간략한 설명을 지정하는 속성
@Operation	description	API에 대한 상세 설명을 지정하는 속성
@Operation	response	API에 대한 응답을 지정하는 속성
@Operation	parameter	API에 대한 파라미터를 지정하는 속성
@Schema		모델에 대한 설명을 명시하는 어노테이션
@Schema	description	모델 자체 혹은 컬럼에 대한 설명을 하는 속성

 

Tag는 3개가 있으며 각 태그 안에 속성 값이 들어가게 된다.

 

여기까지 설정을 하면 기본적인 셋팅은 끝나게 된다.

 

이제 실행을 해보자.

 

 

실행 및 테스트

이미 사용중인 포트인 경우

가장 추천하는 방법은 서버의 Port를 바꿔서 실행을 해보라고 말해보고 싶다.

 

.yml 인 경우

server:
  port: 8080 //8080말고 다른것

 

.properties 인 경우

server.port=8080

 

무조건 8080 혹은 원하는 포트로 하겠다라고 생각하고 ubuntu 혹은 리눅스라면 밑에 명령어를 사용해보자.

$ sudo netstat -tnlp | grep :[사용할 포트]
$ kill -9 [포트를 사용중인 프로세서 아이디]

 

위 명령어를 사용을 한다면 확실하게 처리를 할 수 있을 것이다.

없애버리기..

어떤 프로그램인지 확실하게 안다면 추천을 하겠지만 모르는 프로그램이라면 냅두는 것을 권장한다.

 

 

아래의 주소로 들어가서 확인을 해보자.

http://localhost:8080/swagger-ui/index.html

 

이렇게 적용이 된 모습을 확인 할 수 있다.

밑에 Test API 도 적용이 잘된 모습을 확인할 수 있다.

 

 

아주 성공적이다.

 

 

결과

이제 프로젝트를 진행을 하는 경우 빠르게 Swagger-API 을 추가를 하여 문서를 공유를 할 수 있는 Swagger을 사용을 해보았다.

 

내가 API을 만들어두면 다른 팀원들 혹은 관계자들이 API-docs에 들어와서 어떤 API를 사용을 할 수 있는지 확인을 하고

빠르게 공유를 할 수 있게 되었다.

 

이것이 앞으로의 Spring 공부 혹은 팀플레이에 많은 도움이 될 것이다.