협업을 위해 Swagger 좀 더 잘 사용해보기

목차

1. API 그룹화
2. API 버전 관리 시 @Deprecated 활용하기
3. 명세만 먼저 전달하기
4. Authorize에 jwt 넣을 때 prefix에 Bearer 생략시키기
5. 브라우저 새로고침 후에도 인증정보 유지시키기
6. 기타 자잘한 상세 설정들

 

 

1. API 그룹화

Swagger에서 API를 그룹화하면 여러 엔드포인트를 논리적인 그룹으로 묶어 관리하고 문서를 체계적으로 정리할 수 있습니다.

설정 후에는 위 이미지처럼 관련된 엔드포인트만 볼 수 있어 원하는 API를 쉽게 찾고 관리할 수 있습니다. Swagger에서 API를 그룹화하는 방법은 어떤 라이브러리를 사용하고 있느냐에 따라 다르기 때문에 확인해서 적용하면 됩니다.

springfox-swagger2를 사용하는 경우

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket appApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("APP API")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.app"))
                .paths(PathSelectors.any())
                .build();
    }

    @Bean
    public Docket totalApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("TOTAL API")
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }
}

springdoc-openapi를 사용하는 경우

@Configuration
public class SwaggerConfig {

    @Bean
    public GroupedOpenApi appApi() {
        return GroupedOpenApi.builder()
                             .group("APP API")
                             .pathsToMatch("/app/**")
                             .build();
    }

    @Bean
    public GroupedOpenApi totalApi() {
        return GroupedOpenApi.builder()
                             .group("TOTAL API")
                             .pathsToMatch("/**")
                             .build();
    }
}

 

 

2. API 버전 관리 시 @Deprecated 활용하기

팀 내의 버전 관리 전략에 따라 다르겠지만 API 버전을 관리할 때 일반적으로 @Deprecated 어노테이션을 활용하는 것은 꽤나 유용합니다.

@Tag(name = "[APP] 테스트")
@RestController
@RequestMapping("/app")
public class TestController {

    @Deprecated
    @GetMapping(Version.V1 + "/test")
    public void testV1() {
    }

    @GetMapping(Version.V2 + "/test")
    public void testV2() {
    }
}

class Version {
    public static final String V1 = "/v1";
    public static final String V2 = "/v2";
}

위의 예제에서는 /v1/app/test 엔드포인트가 이제 /v2/app/test로 변경되어야 한다는 가정 하에 V1 버전의 API에 @Deprecated 어노테이션을 사용합니다. 이를 통해 Swagger UI상에서는 다음과 같이 표시됩니다.

@Deprecated 어노테이션이 붙은 엔드포인트는 블라인드 처리되지만, 여전히 Swagger 상에서 API 테스트는 가능합니다. 이를 통해 명세를 전달받은 개발자에게 V1은 곧 사라질 것이라는 것을 알리고, 더 이상 사용하지 않도록 유도할 수 있습니다.

@Deprecated 어노테이션의 속성

추가로 @Deprecated 어노테이션에는 since와 forRemoval이라는 옵션이 존재합니다.

@Deprecated(since = "v1.1.0", forRemoval = true)
@GetMapping(Version.V1 + "/test")
public void testV1() {

}

이 옵션들은 코드의 동작에 집적적으로 영향을 미치지는 않지만, 이 옵션들을 통해 코드를 보는 개발자들에게 유용한 정보를 제공할 수 있습니다. 일반적으로 since에는 @Deprecated가 붙여지게 된 스프린트 혹은 제품의 버전을 명시하고, forRemoval이 true인 경우에는 해당 API가 다음 버전에서 곧바로 제거될 수 있음을 의미합니다.

보통 forRemoval가 false일 경우에는 @Deprecated를 붙인 개발자가 다음 버전에서 직접 코드를 제거하거나 해당 히스토리를 아는 개발자가 삭제합니다. true일 경우에는 '이 코드를 지워도 될까?'라는 걱정 없이 해당 코드를 본 누구나 안심하고 제거할 수 있다는 것을 의미하며 이를 통해 레거시가 된 코드를 곧바로 제거하도록 유도할 수 있습니다.

 

 

3. 명세만 먼저 전달하기

API 로직이 전부 완성된 후 명세를 전달하면 프론트 개발자들이 기다리는 시간이 길어져 리소스를 낭비하게 됩니다. 이럴 때는 아래와 같이 빈 객체만 먼저 전달하여 어떤 Response를 넘겨줄지 명세만 먼저 제공하고, 이후에 로직을 개발하는 방식으로 좀 더 원활하게 협업을 진행할 수 있습니다.

@GetMapping("/test")
public ResponseDto test() {
    // TODO 비즈니스 로직 작성
    return new ResponseDto();
}

이렇게 하면 프론트 개발자는 명세를 기반으로 작업을 시작할 수 있고, 백엔드 개발자는 로직을 차후에 구현할 수 있어 또 다른 명세를 작업하거나 다른 작업을 먼저 진행하는 등 양쪽 모두 작업을 병행하여 효율적으로 진행할 수 있게 됩니다.

 

 

4. Authorize에 jwt 넣을 때 prefix에 Bearer 생략시키기

Swagger UI에서 Authorization에 JWT 토큰을 넣을 때는 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9~'와 같이 'Bearer '를 prefix에 수동으로 명시해야만 합니다. 이런 번거로운 과정을 Swagger 설정을 통해 생략할 수 있습니다.

    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
            .components(new Components()
                            .addSecuritySchemes("Authorization",
                                                new SecurityScheme().type(SecurityScheme.Type.HTTP)
                                                                    .scheme("bearer")
                                                                    .bearerFormat("JWT")
                                                                    .in(SecurityScheme.In.HEADER)
                                                                    .description("JWT 토큰 정보")
                            )
            );
    }

위와 같이 SecurityScheme 설정을 통해 사용자가 Swagger 상에서 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9~' 형식으로만 입력해도 자동으로 'Bearer '가 prefix에 추가되도록 할 수 있습니다. 설정 후 실제로 Swagger에서 API를 요청한 뒤 curl 명령어를 확인해 보면 -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9~"와 같이 Bearer가 자동으로 붙는 것을 확인할 수 있습니다.

 

 

5. 브라우저 새로고침 후에도 인증정보 유지시키기

Swagger는 새로고침하거나 브라우저를 종료한 후 다시 열면 인증 정보가 초기화되어 매번 토큰을 다시 입력해야 하는 번거로움이 있습니다.

이 문제를 해결하기 위해 2020년 3월 29일 PR #5939이 올라왔는데, 이 PR 덕분에 간단한 설정 추가만으로 인증 정보를 유지시킬 수 있게 되었습니다. 설정 방법은 간단한데 yml에 persist-authorization을 true로 설정하면 브라우저를 새로고침하거나 재시작해도 인증 정보가 유지됩니다.

#springdoc swagger
springdoc:
  swagger-ui:
      persist-authorization: true # 브라우저를 새로고침 하더라도 인증정보 유지

새로고침 후에도 인증정보가 남아있는 모습

더 자세한 관련 정보는 configuration.md에서 확인 가능합니다.

 

 

6. 기타 자잘한 상세 설정들

코드에 Swagger 어노테이션을 붙여 API에 대해 더 상세한 정보를 제공할 수 있습니다. 하지만 이 부분은 운영 코드에 Swagger 어노테이션이 많이 침투된다는 점 때문에 Swagger의 단점으로 불리기도 합니다. 따라서 항상 모든 어노테이션을 적용하기보다는 각 API 별로 필요한 부분만 선택적으로 적용하는 것을 권장합니다.(저는 보통 @Tag, @Schema, @Operation까지만 적용하고 필요에 따라 @ApiResponse까지 사용하는 것 같습니다.)

• @Tag: API 그룹 정의
• @Schema: 데이터 모델의 스키마 정의
• @Operation: 특정 엔드포인트의 작업 설명
• @ApiResponse: 특정 엔드포인트의 응답 설명
• @Parameter 메서드 매개변수 설명

추가로 프로퍼티 설정을 통해 Swagger 내 API들의 정렬 순서, 기본으로 전부 펼치기/접기 등의 설정을 통해 가독성도 향상시킬 수 있으니 이 부분도 상황에 맞게 적용하면 도움이 됩니다.