Opis api annotaion jest przestarzały.

Question

W produkcie Swagger @Api opis adnotacji description jest przestarzały.

Czy istnieje nowy sposób dostarczenia opisu?

Answer 1

Powodem, dla którego jest nieaktualny, jest fakt, że poprzednie wersje programu Swagger (1.x) wykorzystywały opis opisujący operacje grupowe w postaci.

W specyfikacji Swagger 2.0, pojęcie tags zostało utworzone i stało się bardziej elastycznym mechanizmem grupowania. Aby zachować zgodność z API, pole description zostało zachowane, więc uaktualnienia byłyby łatwe, ale poprawnym sposobem dodania opisu jest atrybut tags, który powinien odwoływać się do adnotacji @Tag. Numer @Tag umożliwia podanie opisu, a także linków zewnętrznych itp.

Answer 2

Znalazłem rozwiązanie dla mojej aplikacji Spring Boot. Po pierwsze, należy użyć metody tags dla określenia definicji tagi w 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(); 
    } 
} 

potem w RestController wystarczy dodać @Api adnotacji z jednym (lub więcej) z tagów. Na przykład:

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