졸업프로젝트를 진행하면서 공부한 내용 정리!
프로젝트를 진행하면서 swagger를 통해 api명세서를 만들기로 하였다! 이번에 swagger를 처음 사용해보아서 사용법보다 설정 측면?에서 버벅거린 느낌이 있었다. 그래서 그런 사람들이 있다면 이 글이 도움이 되었으면 한다!
먼저 나는 springdoc-openapi 라이브러리를 이용하여 스프링부트 프로젝트의 API문서를 자동화하였다. springdoc은 swagger 버전3 annotation을 따르고 있어서 그 바탕으로 자료를 찾아보았고 공부하였다.
🛸 Swagger 기본 설정
🚦 의존성 추가
build.gradle 파일
dependencies {
implementation ('org.springdoc:springdoc-openapi-ui:1.6.6')
}SwaggerConfig 파일
@Configuration
public class Swagger2Config {
@Bean
public GroupedOpenApi publicApi() {
return GroupedOpenApi.builder()
.group("v1-definition") //묶을 그룹명 지정
.pathsToMatch("/api/**") //어떤 api를 그 그룹에 포함시킬건지
.build();
}
@Bean
public OpenAPI springShopOpenAPI() {
return new OpenAPI()
.info(new Info().title("Springboot Project")
.description("ㅁㅁ 프로젝트 API 명세서")
.version("v0.0.1"));
}
}여기까지만 설정하면 Swagger를 사용할 준비는 다 끝났다! 나머지는 각 Controller에 본인이 추가하고싶은 어노테이션들을 추가해서 Swagger 문서를 더 잘 만들 수 있다.
Controller에서 쓰이는 어노테이션을 잘 정리해주신 블로그가 있어서 여기를 참고하면 많은 도움이 될 것 같다.
또한, swagger를 적용했을 때 swagger가 적용된 화면을 잘 이해하고 싶다면 이 포스트가 많은 도움이 될 것 같다.
🛸 Swagger + jwt
jwt를 사용해서 회원가입을 진행한다면 api를 호출할 때 인증이 필요할 것이다. 이때 이러한 인증 작업을 swagger를 통해 전역으로 설정하면 swagger에서 더 편하게 api를 테스트할 수 있다.
기본적으로 SecurityScheme을 지원하는데 이 속성을 통해 본인이 원하는 보안 방식으로 설정을 할 수 있다.
- HTTP
- Authorization 헤더 이용 - APIKEY
- API의 헤더 이용 - OAUTH2
- OpenIdConnect
이 중에서 HTTP인증과 APIKEY인증이 가장 많이 사용된다. 나는 APIKEY 방식을 사용했기 때문에 APIKEY방식에 대한 코드와 사진을 첨부하겠다!
( HTTP인증은 이 블로그를 참고하면 좋을 것 같다 )
만약 APIKEY방식을 사용한다면 아래와 같이 코드를 작성할 수 있다.
@Configuration
public class SwaggerConfig {
...
@Bean
public OpenAPI openAPI() {
String jwtSchemeName = "AUTH-TOKEN";
SecurityRequirement securityRequirement =
new SecurityRequirement().addList(jwtSchemeName);
Components components = new Components().addSecuritySchemes(jwtSchemeName,
new SecurityScheme()
.name(jwtSchemeName)
.in(SecurityScheme.In.HEADER)
.type(SecurityScheme.Type.APIKEY));
return new OpenAPI()
.info(...)
.addSecurityItem(securityRequirement)
.components(components);
}
}그러면 AUTH-TOKEN이라는 헤더에 토큰을 value로 넣어서 api에 대한 인증 처리를 진행할 수 있다. 위처럼 설정하면 swagger에서 Authorize버튼을 누르면 다음과 같은 팝업창이 보일 것이다.
그러면 value칸에 토큰을 넣고 api에 대한 전체 인증을 진행한 뒤 테스트할 수 있다!
🛸 Swagger + SecurityConfig
버전을 아는 것이 정말 중요하다!
처음에 springdoc이 swagger 버전 3을 따르는지 모르고 무작정 블로그를 보면서 따라하다가 swagger 화면에서 아래와 같은 화면을 마주쳤기 때문이다.
회원가입과 보안을 설정한 다음에 로그인을 하지 않아도 swagger화면에는 접속할 수 있어야 했다. 이때도 수많은 블로그를 돌아다니며 나와 맞는 코드를 보고 적용했다고 생각했는데 위 사진과 같은 오류를 보았다;;
나중에 알아 보니 단순 버전 명시가 잘못된 것이었다! stackoverflow의 이 글을 보고 해결할 수 있었다.
@EnableWebSecurity
@RequiredArgsConstructor
public class SecurityConfig extends WebSecurityConfigurerAdapter {
private final JwtTokenProvider jwtTokenProvider;
@Override
public void configure(WebSecurity web) throws Exception {
web.ignoring().requestMatchers(PathRequest.toStaticResources().atCommonLocations())
.antMatchers(
"/v1/api-docs",
"/v3/api-docs/",
"/swagger-resources",
"/swagger-resources/**",
"/configuration/ui",
"/configuration/security",
"/swagger-ui.html",
"/webjars/**",
"/v1/api-docs/**",
"/swagger-ui/**");
}
...
}위 코드에서 "/v3/api-docs/"부분에서 v1이 아니라 v3으로 적으면 해결되는 문제였다. springdoc이 swagger 버전 3을 따른다는 것을 알면 해결되는 오류였다.
따라서 swagger를 사용하려고 한다면 본인이 사용하는 버전을 먼저 파악하는 과정이 꼭 필요하다!!
참고자료
swagger
[Spring Boot] Swagger를 활용한 API 문서 자동화
Swagger UI 사용법
[API] - Swagger 사용법
