La descrizione di Api annotaion è deprecata

Question

In Swagger, l'annotazione @Apidescription è obsoleta.

Esiste un modo più nuovo di fornire la descrizione?

Answer 1

Il motivo per cui è deprecato è che le precedenti versioni di Swagger (1.x) utilizzavano l'annotazione di descrizione @Api per raggruppare le operazioni.

Nella specifica Swagger 2.0, la nozione di tags è stata creata e ha reso un meccanismo di raggruppamento più flessibile. Per essere conforme all'API, il campo description è stato mantenuto in modo che gli aggiornamenti sarebbero facili, ma il modo corretto di aggiungere una descrizione è l'attributo tags, che dovrebbe fare riferimento a un'annotazione @Tag. Il @Tag consente di fornire una descrizione e anche collegamenti esterni, ecc.

Answer 2

Ho trovato una soluzione per la mia applicazione Spring Boot. In primo luogo, utilizzare il metodo tags per specificare le definizioni di tag nella tua Docket:

@Configuration 
@EnableSwagger2 
public class SwaggerConfig { 

    @Bean 
    public Docket productApi() { 
     return new Docket(DocumentationType.SWAGGER_2).select() 
       .apis(RequestHandlerSelectors.basePackage("my.package")).build() 
       .apiInfo(apiInfo()) 
       .tags(new Tag("tag1", "Tag 1 description."), 
         new Tag("tag2", "Tag 2 description."), 
         new Tag("tag2", "Tag 3 description.")); 
    } 

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

Dopo, in RestController basta aggiungere il @Api annotazioni con uno (o più) dei tag. Ad esempio:

@Api(tags = { "tag1" }) 
@RestController 
@RequestMapping("tag1Domain") 
public class Tag1RestController { ... }