web-dev-qa-db-fra.com

La description de l'annotation Api est obsolète

Dans Swagger, la valeur description de l'annotation @Api est obsolète.

Existe-t-il un moyen plus récent de fournir la description?

swagger
16
Soumitri Pattnaik

J'ai trouvé une solution pour mon application Spring Boot. Premièrement, utilisez la méthode tags pour spécifier les définitions de balises dans votre 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();
    }
}

Après, dans RestController, ajoutez simplement l'annotation @Api avec un (ou plusieurs) de vos tags. Par exemple:

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

C’est le bon moyen d’ajouter une description à la documentation de votre API Swagger pour la version 1.5:

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

La raison pour laquelle il est obsolète est que les versions précédentes de Swagger (1.x) utilisaient l'annotation de description @Api pour regrouper les opérations.

Dans la spécification Swagger 2.0, la notion de tags a été créée et a créé un mécanisme de regroupement plus flexible. Pour être conforme à l'API, le champ description a été conservé afin de faciliter les mises à niveau, mais le moyen correct d'ajouter une description consiste à utiliser l'attribut tags, qui doit référencer une annotation @Tag. Le @Tag vous permet de fournir une description, ainsi que des liens externes, etc.

1
fehguy

Moi aussi, je me suis demandé quoi faire avec les utilisations de la description obsolète (apparaissant comme des avertissements dans mon IDE). 

Eh bien, à y regarder de plus près, il s'est avéré que description n'est utilisé nulle part dans Swagger UI . Après cela, la solution (dans notre cas *) est devenue claire: supprimez simplement ces descriptions. 

(* Dans notre base de code, avec des noms de classe et de méthode propres, etc., le lecteur du code n'avait certainement pas besoin de telles "descriptions d'API". J'aurais toléré que ces bits de bruit liés à Swagger soient ajoutés à la base de code s'ils ajoutaient une certaine valeur dans Swagger UI, mais comme ils ne l’avaient pas fait, la seule chose sensée était de les jeter.) 

0
Jonik