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.

Answer 1

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.