java - 不推荐使用 Api 注释的描述

Question

在 Swagger 中，@Api注释的description元素已被弃用。

已弃用。 未在 1.5.X 中使用，保留用于旧版支持。

是否有更新的方式来提供描述？

Answer 1

我为 Spring Boot 应用程序找到了两种解决方案：

1.基于Swagger 2：

首先，使用tags指定Docketbean 中标签定义的方法：

@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指定OpenAPIbean 中的标签定义的方法：

@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 { ... }

Answer 2

这是在 Swagger v1.5 的 Swagger API 文档中添加描述的正确方法：

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

Answer 3

不推荐使用它的原因是以前的 Swagger 版本（1.x）使用@Api​​描述注释来分组操作。

在 Swagger 2.0 规范中，tags创建了 的概念，并提出了更灵活的分组机制。为了符合 API，该description字段被保留，因此升级很容易，但添加描述的正确方法是通过tags属性，它应该引用@Tag注释。@Tag允许您提供描述以及外部链接等。

Answer 4

我尝试了上述解决方案，但它们对我不起作用。

要为文档添加标题和描述，您可以创建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()));
  }
}

上面的代码会产生一个描述，如下面的屏幕截图所示。

Answer 5

我也想知道如何处理已弃用的用途description（在我的 IDE 中显示为警告）。

好吧，仔细检查后发现，description 在 Swagger UI 的任何地方都没有使用它。之后解决方案（在我们的例子中*）变得清晰：只需删除这些描述。

（*在我们的代码库中，使用干净的类和方法名称等，对于代码的读者来说，当然不需要这样的“API 描述”。如果他们在代码库中添加这些与 Swagger 相关的噪音，我会容忍Swagger UI 中的一些价值，但由于它们没有，唯一明智的做法就是把它们扔掉。）

Answer 6

我发现以下工作是通过结合构建这个答案@Api的和注释来实现的。@Tag

注解的 tags 字段中的@Api值需要与注解的 name 字段中的值匹配@Tag。

@Api(tags = "Controller API")
@Tag(name = "Controller API", description = "This controller performs API operations")
public class ReportStatusConsumerController {

}

Answer 7

一个老问题，但可能有助于使用 swagger 3

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    // Swagger configuration
    @Bean
    public Docket api() {

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo( this.apiInfo())
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("API Reference").version("1.0.0")
                .description("something")
                .license("Apache 2.0")
                .build();
    }

    public void addResouceHandler(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}