Api annotation's description is deprecated

Question

In Swagger, the @Api annotation's description element is deprecated.

Deprecated. Not used in 1.5.X, kept for legacy support.

Is there a newer way of providing the description?

Scapula

Which Version do you refer to? – Primo

github.com/swagger-api/swagger-core/wiki/Annotations-1.5.X or maybe docs.swagger.io/swagger-core/current/apidocs/index.html?io/… might help – Radarman

@Primo I am using 2.4.0 version (springfox) – Scapula

As i can see, only three attibutes are deprecated – Primo

@Jens, if it is deprecated, it means that there is a newer alternative, what is that? – Scapula

Deprecated means, that it won't be used any more in a later version. It doesn't necessarily mean, that there is a newer alternative. – Subsellium

@Subsellium ohh I see, Thanks :) – Scapula

@SoumitriPattnaik you found any solution ? – Bacteria

Answer 1

I found two solutions for Spring Boot application:

1. Swagger 2 based:

Firstly, use the tags method for specify the tags definitions in your Docket bean:

@Configuration
@EnableSwagger2
public class Swagger2Config {
    
    public static final String TAG_1 = "tag1";

    @Bean
    public Docket productApi() {
        return new Docket(DocumentationType.SWAGGER_2).select()
                .apis(RequestHandlerSelectors.basePackage("my.package")).build()
                .tags(new Tag(TAG_1, "Tag 1 description."))
                // Other tags here...
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("My API").version("1.0.0").build();
    }
}

After, in RestController just add the @Api annotation with one (or more) of the your tags:

@Api(tags = { SwaggerConfig.TAG_1 })
@RestController
@RequestMapping("tag1-domain")
public class Tag1RestController { ... }

2. Swagger 3 based (OpenAPI):

Similarly, use the addTagsItem method for specify the tags definitions in your OpenAPI bean:

@Configuration
public class OpenApiConfig {

    public static final String TAG_1 = "tag1";

    @Bean
    public OpenAPI customOpenAPI() {
        final Info info = new Info()
                .title("My API")
                .description("My API description.")
                .version("1.0.0");

        return new OpenAPI().components(new Components())
                .addTagsItem(createTag(TAG_1, "Tag 1 description."))
                // Other tags here...
                .info(info);
    }

    private Tag createTag(String name, String description) {
        final Tag tag = new Tag();
        tag.setName(name);
        tag.setDescription(description);
        return tag;
    }

}

Finally, in RestController just add the @Tag annotation:

@Tag(name = OpenApiConfig.TAG_1)
@RestController
@RequestMapping("tag1-domain")
public class Tag1RestController { ... }

Calomel

Description of Tag not coming on swagger UI – Bacteria

@Bacteria - It does if you use a new enough version of Swagger (eg. 2.9.x) – Continental

@Calomel - Perfect. However if there is any way if we can reduced font size? – Hollow

Great, This worked for me too. However, I am wondering if there is any way to add line breaks in the description. I tried putting \n and <br> – Jollity

This helped for 2.9.2 version! – Zymosis

Don't you face the new io.swagger.annotations.Tag - is abstract, cannot be instantiated? Should be springfox.documentation.service.Tag. – Shields

Yes, I'm using the springfox.documentation.service.Tag, following the tags (builder method) signature. – Calomel

so I have to add description inside Swagger2Config. So If I have 20 controllers I have to put all of them in the Swagger2Config. IMHO it would be better to have it inside the same controller – Film

Answer 2

This is the correct way to add description to your Swagger API documentation for Swagger v1.5:

@Api(tags = {"Swagger Resource"})
@SwaggerDefinition(tags = {
    @Tag(name = "Swagger Resource", description = "Write description here")
})
public class ... {
}

Minnick

This looks like a good way to do it, but what if you are reusing the tag on multiple APIs ? where would u put SwaggerDefinition ? I've tried to put it on my SwaggerConfig bean, but it was not taken into account. Only the programatically way worked for me. – Bradwell

@zhuguowei, Did you found the way to use it in 2.9.2? Help me if you know how to use it in a 2.9.2 version. – Sartor

@ShivarajaHN please see falvojr 's answer – Krupp

Unfortunately, this solution does not work, see github.com/swagger-api/swagger-core/issues/1476. – Sino

GitHub issue for this solution not working: github.com/swagger-api/swagger-core/issues/3737 – Chui

the idea is correct, but not the implementation, for correct implementation see 1. Swagger 2 based: from falvojr - set @Api(tags = {"User"}) - that User appears in Swagger page and in SwaggerConfig.java for new Docket() after build add .tags(new Tag("User", "some user actions"); – Agist

Answer 3

The reason why it's deprecated is that previous Swagger versions (1.x) used the @Api description annotation to group operations.

In the Swagger 2.0 specification, the notion of tags was created and made a more flexible grouping mechanism. To be API compliant, the description field was retained so upgrades would be easy, but the correct way to add a description is though the tags attribute, which should reference a @Tag annotation. The @Tag allows you to provide a description and also external links, etc.

Carven

An example would be much appreciated! – Minuteman

Answer 4

I tried above solutions but they didn't work for me.

To add a title and description to the documentation you create ApiInfo and Contact objects like in example below. Then you simply add apiInfo object to your Swagger Docket.

import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;

@EnableSwagger2
@Configuration
public class SwaggerConfig {

  private Contact contact = new Contact("", "", "");
  private ApiInfo apiInfo = new ApiInfo(
      "Backoffice API documentation",
      "This page documents Backoffice RESTful Web Service Endpoints",
      "1.0",
      "",
      contact,
      "",
      "");

  @Bean
  public Docket api() {
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo)
        .select()
        .apis(RequestHandlerSelectors.basePackage(
            PaymentsController.class.getPackage().getName()
        ))
        .paths(PathSelectors.ant("/api/v1/payments" + "/**"))
        .build()
        .useDefaultResponseMessages(false)
        .globalOperationParameters(
            newArrayList(new ParameterBuilder()
                .name("x-authorization")
                .description("X-Authorization")
                .modelRef(new ModelRef("string"))
                .parameterType("header")
                .required(false)
                .build()));
  }
}

Above code produces a description like in a screenshot below.

Frisby

I've added your image - pending review... but it seems you may have answered another question here! The question is about description attribute of @Api annotation - which was being rendered per class/tag/group of entry points, not the whole application's API as in your screenshot – Unsociable

Answer 5

I too wondered what to do about uses of the deprecated description (showing up as warnings in my IDE).

Well, on closer inspection it turned out that description is not used anywhere in Swagger UI. After that the solution (in our case*) became clear: simply remove those descriptions.

(*In our codebase, with clean class and method names etc, there was certainly no need for such "API descriptions" for the reader of the code. I would have tolerated having these bits of Swagger-related noise in the codebase if they added some value in Swagger UI, but since they didn't, the only sensible thing was to throw them away.)

Bankruptcy

Answer 6

I found that the following works by combining both the @Api and @Tag annotations building off of this answer.

The value within the tags field of the @Api annotation needs to match the value within the name field of the @Tag annotation.

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

}

Giulio

Answer 7

An old question but may help using swagger 3

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    // Swagger configuration
    @Bean
    public Docket api() {

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo( this.apiInfo())
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("API Reference").version("1.0.0")
                .description("something")
                .license("Apache 2.0")
                .build();
    }

    public void addResouceHandler(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

Moonshine