1

I'm trying to provide formatted description to a controller in Swagger. However I can't find any annotation that enables it. Currently it looks like this:

@Api(tags = {"Change timezone"})

enter image description here

However I would like to provide meaningful description. The description parameter withing @Api is deprecated.

Yoda
  • 17,363
  • 67
  • 204
  • 344

2 Answers2

1

It seems that, there is a hole with this deprecation. This feature has been deprecated but no other Annotation has replaced that functionality.

For now it seems that you can only add description programmatically

@Bean 
public Docket commonDocketConfig() { 

 return new Docket(DocumentationType.SWAGGER_2) .select() 
       .apis(RequestHandlerSelectors.basePackage("com.company")) 
       .paths(PathSelectors.any()) 
       .build() .apiInfo(apiEndPointsInfo()) 
       .tags(new Tag("Change timezone", "your description")); 
 }

Issue can be tracked here

@Api description deprecated without any alternative

You can try also with

@Api(tags = {"Change timezone"})
@SwaggerDefinition(tags = {
        @Tag(name = "Change timezone", description = "your Description")
})
public class YourController {
}

This annotation however already has an open bug for not behaving correctly @SwaggerDefinition bug

Panagiotis Bougioukos
  • 15,955
  • 2
  • 30
  • 47
0

Since it looks like yours is a PUT operation, try doing something like this. You can also write it like this:

@OA(
    @PUT(
        tags = {"Change timezone"},
        description = "Your description here",
        etc...
    )
)

Swagger PUT operation tags

Here is the link to where I took the image: https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Annotations#operation Try reading more on it there.

J-Dumas
  • 79
  • 6
  • I don't want to describe controller action but controller itself it is stated in the question. – Yoda Mar 11 '21 at 08:59