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

Я нашел два решения для приложения Spring Boot:

1. Swagger 2 на основе:

Во-первых, используйте метод tags для указания определений тегов в вашем bean-компоненте Docket:

@Configuration
@EnableSwagger2
public class Swagger2Config {
    
    public static final String TAG_1 = "tag1";

    @Bean
    public Docket productApi() {
        return new Docket(DocumentationType.SWAGGER_2).select()
                .apis(RequestHandlerSelectors.basePackage("my.package")).build()
                .tags(new Tag(TAG_1, "Tag 1 description."))
                // Other tags here...
                .apiInfo(apiInfo());
    }

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

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

@Api(tags = { SwaggerConfig.TAG_1 })
@RestController
@RequestMapping("tag1-domain")
public class Tag1RestController { ... }

2. на основе Swagger 3 (OpenAPI):

Точно так же используйте метод addTagsItem для указания определений тегов в вашем bean-компоненте OpenAPI:

@Configuration
public class OpenApiConfig {

    public static final String TAG_1 = "tag1";

    @Bean
    public OpenAPI customOpenAPI() {
        final Info info = new Info()
                .title("My API")
                .description("My API description.")
                .version("1.0.0");

        return new OpenAPI().components(new Components())
                .addTagsItem(createTag(TAG_1, "Tag 1 description."))
                // Other tags here...
                .info(info);
    }

    private Tag createTag(String name, String description) {
        final Tag tag = new Tag();
        tag.setName(name);
        tag.setDescription(description);
        return tag;
    }

}

Наконец, в RestController просто добавьте аннотацию @Tag:

@Tag(name = OpenApiConfig.TAG_1)
@RestController
@RequestMapping("tag1-domain")
public class Tag1RestController { ... }

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

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

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

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

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

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

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

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

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

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

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