Question

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

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

Answer 1

我找到了Spring Boot应用程序的解决方案。首先，使用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 { ... }

Answer 2

这是为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

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

好吧，经过仔细检查，结果发现description 在Swagger用户界面的任何地方都没有使用。之后，解决方案（在我们的情况下为*）变得清晰起来：只需删除这些描述。

（**在我们的代码库中，使用干净的类和方法名称等，对于代码阅读者来说当然不需要这种“ API描述”。我可以忍受在代码库中包含这些与Swagger相关的噪声如果他们在Swagger用户界面中增加了一些价值，但由于没有这样做，唯一明智的选择就是将其丢弃。）

Answer 5

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

要在文档中添加标题和说明，请创建 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()));
  }
}

上面的代码产生的描述类似于下面的屏幕截图。

有谁能获得比我更高声誉的人，请编辑帖子并添加此图片https://i.stack.imgur.com/YUjbr.png

不推荐使用Api注释的描述

5 个答案: