Описание аннотации API устарело

Ответ 1

Я нашел решение для моего приложения загрузки Spring. Во-первых, используйте метод tags для определения определений тегов в 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();
    }
}

После того, как в RestController просто добавьте аннотацию @Api одним (или более) тегами. Например:

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

Ответ 2

Это правильный способ добавить описание в документацию Swagger API для v1.5:

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

Ответ 3

Причина, по которой она устарела, заключается в том, что предыдущие версии Swagger (1.x) использовали аннотацию описания @Api для групповых операций.

В спецификации Swagger 2.0 было создано понятие tags и создано более гибкий механизм группировки. Чтобы соответствовать API, поле description было сохранено, поэтому обновление было бы простым, но правильный способ добавления описания - это атрибут tags, который должен ссылаться на аннотацию @Tag. @Tag позволяет вам предоставить описание, а также внешние ссылки и т.д.

Ответ 4

Я тоже задавался вопросом, что делать с использованием устаревшего description (отображаемого как предупреждения в моей IDE).

Что ж, при ближайшем рассмотрении выяснилось, что description нигде в Swagger UI не используется. После этого решение (в нашем случае *) стало ясным: просто удалите эти описания.

(* В нашей кодовой базе, с чистыми именами классов и методов и т.д., Конечно, не было необходимости в таких "описаниях API" для читателя кода. Я бы допустил наличие этих битов шума, связанного с Swagger, в кодовой базе, если бы они добавили какая-то ценность в Swagger UI, но так как они этого не сделали, единственной разумной вещью было выбросить их.)

Ответ 5

Я пробовал вышеуказанные решения, но они не помогли мне.

Чтобы добавить заголовок и описание к документации, вы создаете объекты ApiInfo и Contact, как в примере ниже. Затем вы просто добавляете объект apiInfo в свой список Swagger.

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()));
  }
}

Выше код создает описание, как на скриншоте ниже.