[Spring] SpringBoot Swagger 연동 (3.x ver)

Spring Boot 3.0 Swagger 연동

SM에 있을 때는 자주 사용하지 않았지만, SI로 넘어오게 되면서 처음 접했던 부분이 바로 이 Swagger입니다.

팀 프로젝트를 진행하거나 포트폴리오를 작성할 때 API 문서를 작성할 일이 많아지는데, Swagger를 통하여 구성된 API를 자동으로 구성해 주고, 테스트가 가능하며, 이러한 API 문서를 프론트 개발자와 공유하며 소통이 가능하게 합니다.

 

Swagger 라이브러리 추가

Spring Boot 3.0 이후에 사용할 수 있는 최신 버전의 Swagger 라이브러리를 Gradle에 등록했습니다. Spring Boot 2. x 버전에서 사용하게 된다면 빌드 오류가 날 수 있으니 낮은 버전이라면 더 낮은 버전의 라이브러리를 사용해주세요.

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

 

Swagger 관련 파일 설정

등록한 설정을 말씀드리자면 tags-sorter : alpha 옵션은 태그를 알파벳순 정렬하고 operations-sorter: alpha Swagger UI에서 API들을 알파벳순 정렬하며 doc-expansion : none 문서 확장 비활성화를 의미합니다. 해당 설정은 제가 설정한 기본 옵션들이고, 더 다양한 옵션들이 있으니 부족하다고 느끼면 더 추가해서 사용하셔도 됩니다.

springdoc:
  swagger-ui:
    tags-sorter: alpha
    operations-sorter : alpha
    doc-expansion : none

 

Swagger Config 파일 생성 

 

SecuritySheme 객체를 생성하여 JWT 토큰 값을 넣을 구성요소를 만들어주고, API가 실행될 때 Header에 넣어 요청되도록 설정했으며 위의 작성한 부분들을 OpenAPI에 추가하여 빈으로 등록합니다. 이때 Swagger 문서의 이름이나 버전 명세도 가능하니 추가해 주셔도 됩니다.

@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI openAPI(){
        SecurityScheme securityScheme = new SecurityScheme()
                .type(SecurityScheme.Type.HTTP).scheme("bearer").bearerFormat("JWT")
                .in(SecurityScheme.In.HEADER).name("Authorization");
        SecurityRequirement securityRequirement = new SecurityRequirement().addList("bearerAuth");

        return new OpenAPI()
                .components(new Components().addSecuritySchemes("bearerAuth", securityScheme))
                .security(Collections.singletonList(securityRequirement));
    }
}

 

 

Swagger Security 설정

 

Swagger를 설정했으니 Swagger URL로 접근했을 때 토큰 검증 없이 붙을 수 있도록 경로를 설정했습니다. 그렇지 않는다면 403 오류를 호출하게 되니까 전체 허용해 주시거나, 혹은 아래와 같이 설정합니다. 혹시 모르니까 저는 다양하게 경로마다 권한을 허용해 주었습니다. 

.authorizeHttpRequests(requests ->
        requests.requestMatchers(
        "/api-docs/**",
        "/v3/api-docs/**",
        "/v3/api-docs/swagger-config/**",
        "/swagger-ui.html",
        "/swagger-resources",
        "/swagger-resources/**",
        "/configuration/ui",
        "/configuration/security",
        "/webjars/**",
        "/swagger-ui/**").permitAll()

 

시큐리티에 권한을 설정하고 나서 실행시켜 준다면 http://localhost:9001/swagger-ui/index.html?configUrl=/api-docs/swagger-config#/ 주소로 접속하여 아래 사진처럼 Swagger 설정을 해준 API들이 나오게 됩니다. 처음에는 해당 링크를 몰라 혼동될 수 있으니 위 주소처럼 입력해서 접속하시면 됩니다.

 

Swagger

 

Swagger API 등록

아래의 코드는 예제로 작성한 코드입니다. 각 하나씩 설명해 드리자면, Tag는 이 Controller의 이름을 설정해 줍니다.

Operation은 문서에 이 API에 대한 설명을 해줄 수 있습니다.

ApiResponse는 에러가 발생했을 때, 에러의 설명을 부가할 수 있습니다. 

 

@Tag(name = "회원")
@RestController
@RequestMapping("/members")
@RequiredArgsConstructor
public class MemberController {


    @Operation(summary = "내 정보",description = "내 정보 불러오기")
    @ApiResponse(responseCode = "200", description = "success")
    @ApiResponse(responseCode = "400", description = "fail")
    @GetMapping
    public ResponseEntity<Object> getMe(Authentication authentication) {
        MemberDetails memberDetails = (MemberDetails) authentication.getPrincipal();
        return ResponseEntity.ok(memberDetails);
    }
}

 

이렇게 Swagger를 연동하여 실행까지 해봤습니다. 사용하기 매우 편리해서 없으면 서운할 것 같다는 생각이 드는 라이브러리입니다. 해당 글을 보고 안되는 부분은 댓글을 남겨주셔도 됩니다. 다음 글은 이전에 작성했던 Security + JWT를 Swagger를 통해 테스트해 보겠습니다.