Swagger란 무엇인가
Swagger는 API의 문서를 자동으로 만들어주는 특별한 프레임워크이다.
그렇다면 왜 API 문서를 만들어야 하는가??우리는 다양한 플랫폼에서 API를 이용하기 위해 REST API를 개발하기도 한다.
혹은 프론트서버와 백엔드서버의 분리가 된 환경에서 데이터를 주고 받기 위해서도 API를 개발한다.만약 API 서버는 다 만들었는데 그걸 사용하는 개발자들에게 일일히 설명하는 것은 곤욕이다.
그렇다면 문서로 API의 사용법과 명세를 남기는 것이 효율적이기 때문이다.Swagger를 사용하면 API 문서를 자동으로 만들어주기 때문에 문서 작성에 할애하는 시간도 줄어든다.
Swagger를 사용하기 전에 알아야할 것.
Swagger를 사용하기 위해 먼저 알고 있으면 좋은 것이 있다.
Swagger는 2가지의 라이브러리가 존재한다.
- Spring-fox : 2020년 이후로 업데이트가 없음. (Spring Boot 3버전 이상 사용시 문제가 생길 수 있음)
- Spring-Doc : 꾸준하게 업데이트가 되는 중.
위 2가지 라이브러리에 차이가 위 처럼 존재하는데 Spring-fox가 요즘은 업데이트를 하고 있다는 소식이 들려온다. 하지만 대부분 Spring-Doc을 사용하는 것이 좋을 것 같다는 의견이 많다.
Swagger 설정
Swagger를 사용하기 위해서는 몇가지 설정이 필요하다.
Dependencies
dependencies {
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.2'
}위와 같이 의존성을 추가해주자. 나는 Gradle을 사용하고 있다.
OpenApiConfig
@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);
}
}위와 같이 설정파일을 만들어주자. OpenAPI를 반환하는 메서드를 보면
@Value으로 가져오는 값이 있다. properties에 추가할 사항이 있다.
application.properties
properties로 구성해도 되고, yml 파일로 구성해도 된다.
나는 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| 매개변수 이름 | 기본값 | 설명 |
|---|---|---|
| springdoc.version | 그냥 버전 기록용 | |
| spring.swagger-ui.path | /swagger-ui.html | String, Swagger-ui HTML 문서의 사용자 정의 경로 |
| springdoc.swagger-ui.tags-sorter | API 태그 목록에 정렬을 적용(alpha -> 영숫자순으로 경로별로 정렬) | |
| springdoc.swagger-ui.operations-sorter | API 작업 목록에 정렬을 적용(alpha -> 영숫자 경로 기준 정렬) | |
| springdoc.api-docs.path | /v3/api-docs | String, Json 형식의 OpenAPI 문서의 사용자 정의 경로 |
| springdoc.packages-to-scan | * | List of Strings.스캔할 패키지 목록(쉼표로 구분) |
| springdoc.default-consumes-media-type | application/json | String. 기본값은 미디어 유형을 사용합니다. |
| springdoc.default-produces-media-type | / | String. 기본값은 미디어 유형을 사용합니다. |
TestAPI
Swagger ui html 문서에 api 내용을 추가해보기 위해 새로운 테스트용 api를 아래와 같이 만들자.
테스트용 API
@Tag(name = "테스트", description = "테스트 관련 API")
@RestController
public class TestController {
@Operation(
summary = "테스트 메서드",
description = "테스트 메서드입니다.",
responses = {
@ApiResponse(
responseCode = "200",
description = "테스트 성공함."
),
@ApiResponse(
responseCode = "400",
description = "테스트 실패함."
)
}
)
@GetMapping("/test/{no}")
public ResponseEntity<TestViewResponse> getTestData(
@Parameter(description = "테스트할 숫자", example = "testNo")
@PathVariable(name = "no") int no) {
if(no <= 0) {
return ResponseEntity.status(HttpStatus.BAD_REQUEST).build();
}
TestViewResponse response = new TestViewResponse();
response.setTestNo(no);
response.setTestBody("성공");
return ResponseEntity.status(HttpStatus.OK).body(response);
}
}위와 같이 테스트용 API에 Swagger의 어노테이션을 사용해서 API에 대한 설명을 했다.
이제 Swagger-ui html에 접속해서 확인해보자.
Swagger-ui Html
http://localhost:[포트번호]/swagger-ui/index.html
해당 Url로 접속해서 확인할 수 있다.
위와 같이 나온다면 정상적으로 Swagger 설정이 끝났다. 추가적인 설정은 입맛에 맞게 더 추가하고
신나게 API를 개발하면서 문서를 작성하자.
자주쓰는 어노테이션은 아래에 표로 정리해두겠다.
| 태그 | 속성 | 설명 |
|---|---|---|
| @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 | 모델 자체 혹은 컬럼에 대한 설명을 하는 속성 |
Swagger 3과 Swagger 2의 어노테이션 차이가 있어 아래 표를 첨부한다.!
