Swagger2 문서화시 tags의 description deprecated 대체재

스웨거2를 이용하여 문서화를 진행하던 도중 API별로 깔끔하게 모아서 정리하고 싶었으나

아래와 같이 @Api 어노테이션의 description이 deprecated되어 사용할 수 없는 문제가 발생했다.

 

@Api(tags = "tag", description = "태그") //deprecated
public class MyApiController {

 

해당 문제에 대해 찾아보니 이미 2015년 부터 해당 issue가 있었고 2019년도까지는 deprecated된 속성을 계속 써왔던걸로 보인다.

 

원인

해당 문제에 대한 원인은 Swagger 1.X 버전에서는 @Api의 description 속성을 통해 그룹화했었지만

Swagger 2.X 버전에서 tags라는 속성을 통해 그룹화를 하게 되며 해당 어노테이션간의 충돌을 막고자 한 것으로 보인다.

 

https://stackoverflow.com/questions/38074936/api-annotations-description-is-deprecated#:~:text=The%20reason%20why%20it's%20deprecated,a%20more%20flexible%20grouping%20mechanism.

Api annotation's description is deprecated

 

해결 방법

간단하게 스웨거3로 버전을 올리는 방법이 있다.

하지만 본인은 스웨거3로 시작했다가 이런 저런 버그를 맛보고 2.X 버전으로 내려온터라 다른 방법을 찾아야 했고 해결 방법은 다음과 같다.

 

Swagger 설정 파일에 다음과 같이 tags를 설정한다. 

필요한만큼 쭉 늘려나가면 된다.

 

@Bean
public Docket swaggerApi() {
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(this.swaggerInfo())
            .select()
            .apis(RequestHandlerSelectors.any())
            .paths(PathSelectors.ant("/api/**"))
            .build()
            .tags(  new Tag("a", "description"),
                    new Tag("b","description"),
            );
}

 

그 이후에 아래처럼 해당 tag를 가져다가 쓰는 방식으로 사용하면 된다.

 

@Api(tags = "a")
public class MyApiController {

 

그 외

다른 2가지 방식이 더 있길래 둘 다 시도해봤으나 제대로 동작하지 않았다.

 

@Api와 @Tag를 같이 사용하는 방법

 

동작하지 않음

@Api(tags = "Controller API")
@Tag(name = "Controller API", description = "This controller performs API operations")
public class ReportStatusConsumerController {

}

 

@SwaggerDefinition

 

원하는 방식으로 동작하지 않음

@SwaggerDefinition(
        info = @Info(
                description = "Gets the weather",
                version = "V12.0.12",
                title = "The Weather API",
                termsOfService = "http://theweatherapi.io/terms.html",
                contact = @Contact(
                   name = "Rain Moore", 
                   email = "rain.moore@theweatherapi.io", 
                   url = "http://theweatherapi.io"
                ),
                license = @License(
                   name = "Apache 2.0", 
                   url = "http://www.apache.org/licenses/LICENSE-2.0"
                )
        ),
        consumes = {"application/json", "application/xml"},
        produces = {"application/json", "application/xml"},
        schemes = {SwaggerDefinition.Scheme.HTTP, SwaggerDefinition.Scheme.HTTPS},
        tags = {
                @Tag(name = "Private", description = "Tag used to denote operations as private")
        }, 
        externalDocs = @ExternalDocs(value = "Meteorology", url = "http://theweatherapi.io/meteorology.html")
)
public interface TheWeatherApiConfig {
}

 

레퍼런스

https://github.com/swagger-api/swagger-core/issues/1476

swagger 2.0 why api description has been deprecated ? · Issue #1476 · swagger-api/swagger-core