Swagger?
스웨거는 개발자가 Rest 서비스를 설계, 빌드, 문서화, 소비하는 일을 도와주는 대형 도구 생태계의 지원을 받는 오픈 소스 소프트웨어 프레임워크이다. ( 라고 정의가 되어 있음 )
여러 자료들과 작업을 진행해본 결과, Swagger를 가장 많이 사용하는 이유는 프로젝트의 API 문서 자동화를 위해서였다. ( 물론 API 문서 자동화 이외에도 많은 기능을 포함하고 있다. )
왜 Swagger를 선택했는 가?
API 문서 자동화 Tool은 여러가지가 있다. 그 중에서도 Spring 진영에서 많이 사용하는 Spring Rest Docs가 있다. 해당 도구는 테스트를 동시에 진행하기 때문에 큰 프로젝트에 좀 더 적합하다고 생각한다. ( 본인이 Spring Rest Docs 적용을 해보았을 때, 설정도 매우 번거롭고, 이후 테스트코드 작성도 시간이 소요된다. )
스웨거 적용 역시 프로젝트 코드에 어노테이션 등으로 더러워지지만 일단 소규모 프로젝트를 진행할 때는 스웨거만 한 게 없다고 생각한다.
스웨거를 잘 찾아보면 Swagger Fox 가 있고 SpringDoc ( OpenAPI ) 가 있는 데, Fox는 2019년 업데이트를 마지막으로 진행되지 않는 프로젝트인 것 같다. 따라서 OpenAPI를 적용하기로 했다.
Gradle
Gradle이 간단한게 정말 좋다. Rest Docs는 문서를 저장하고, 이동하고,, 아무튼 과정이 복잡하다. Swagger 적용 Gradle은 단 한 줄만 추가해주면 된다. ( Spring Boot 기준 )
``` 무수히 많은 Gradle 요청 ```
// Swagger SpringDoc
implementation 'org.springdoc:springdoc-openapi-ui:1.6.9'2023년 01월 현재 시점 사용가능한 버전 중 하나이다.
스택
Spring Boot 2.7.7
Java 11
Swagger Configuration
@Configuration
public class SpringDocsConfig {
@Bean
public OpenAPI openAPI(
@Value("${springdoc.version}") String version
) {
Info info = new Info()
.title("Bonheur API 문서") // 타이틀
.version(version) // 문서 버전
.description("잘못된 부분이나 오류 발생 시 바로 말씀해주세요.") // 문서 설명
.contact(new Contact() // 연락처
.name("Hwan")
.email("thirdshine@gmail.com"));
return new OpenAPI()
.info(info);
}
}Configuration 마저 너무나 간단해버려서.. Spring Boot를 이용해서 서버 개발을 어느정도 진행해보았다면 공식문서를 찾아보지 않고도 대충 어떤 코드인지 바로 이해할 수 있다.
타이틀, 버전, 문서 설명, 연락처들을 기입하여 API 문서를 열었을 때, 보이는 정보들을 커스터마이즈할 수 있다.
// Security 스키마 설정
SecurityScheme bearerAuth = new SecurityScheme()
.type(SecurityScheme.Type.HTTP)
.scheme("bearer")
.bearerFormat("Authorization")
.in(SecurityScheme.In.HEADER)
.name(HttpHeaders.AUTHORIZATION);
// Security 요청 설정
SecurityRequirement addSecurityItem = new SecurityRequirement();
addSecurityItem.addList("Authorization");
return new OpenAPI()
// Security 인증 컴포넌트 설정
.components(new Components().addSecuritySchemes("Authorization", bearerAuth))
// API 마다 Security 인증 컴포넌트 설정
.addSecurityItem(addSecurityItem)
.info(info);위 코드를 추가하면 스웨거 API 문서에 인증을 추가할 수 있다.
Application.yml
springdoc:
swagger-ui:
enabled: true
path: '/api/api-docs.html'
try-it-out-enabled: false
version: 'v1'application yml 작성도 너무나 간단하고 명료하다. path를 Default를 사용하지 않으려면 별도로 지정해주면 되고, try-it-out을 통해 스웨거에서 테스트가 가능한데 이를 on하거나 off할 수 있다. version을 명시해서 API 문서의 버전을 지정할 수 도 있다. 더 많은 키워드들이 존재하는데 아래 문서를 참고하면 된다.
마무리
너무나 간단하게 적용 가능한 스웨거 API 명세서를 알아봤다. 너무 기초적인 설정과 변수들, properties만 다루고 있기 때문에 더 딥하게 설정하여 사용하기를 원한다면 공식문서를 참고하는 것이 좋다.. 앞으로 프로젝트 코드에 명세 코드를 추가하는 작업을 할 예정이다.
