不推荐使用 Api 注释的描述

Posted

技术标签:

【中文标题】不推荐使用 Api 注释的描述【英文标题】:Api annotation's description is deprecated 【发布时间】:2016-10-30 16:56:21 【问题描述】:

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

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

有更新的描述方式吗?

【问题讨论】:

你指的是哪个版本? github.com/swagger-api/swagger-core/wiki/Annotations-1.5.X 或者 docs.swagger.io/swagger-core/current/apidocs/index.html?io/… 可能会有所帮助 @Jens 我使用的是 2.4.0 版本(springfox) 如我所见,只有三个属性被弃用 Deprecated 表示在以后的版本中将不再使用它。这并不一定意味着有更新的替代方案。 【参考方案1】:

我为 Spring Boot 应用找到了两种解决方案:

1. Swagger 2 基于:

首先,使用tags 方法在Docket bean 中指定标签定义:

@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 方法在OpenAPI bean 中指定标签定义:

@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 UI 上的描述 @Kick - 如果你使用足够新的 Swagger 版本(例如 2.9.x) @falvojr - 完美。但是,如果我们可以减小字体大小,有什么办法吗? 太好了,这对我也有用。但是,我想知道是否有任何方法可以在描述中添加换行符。我试着把 \n 和 你不面对new io.swagger.annotations.Tag - 是抽象的,不能被实例化吗?应该是springfox.documentation.service.Tag【参考方案2】:

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

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

【讨论】:

这看起来是个不错的方法,但是如果您在多个 API 上重用标签怎么办?你会把 SwaggerDefinition 放在哪里?我试图把它放在我的 SwaggerConfig bean 上,但没有考虑到它。只有编程方式对我有用。 @zhguuowei,你找到2.9.2的使用方法了吗?如果你知道如何在 2.9.2 版本中使用它,请帮助我。 @ShivarajaHN 请查看 falvojr 的回答 很遗憾,此解决方案不起作用,请参阅github.com/swagger-api/swagger-core/issues/1476。 此解决方案的 GitHub 问题不起作用:github.com/swagger-api/swagger-core/issues/3737【参考方案3】:

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

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

【讨论】:

一个例子将不胜感激!【参考方案4】:

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

要为文档添加标题和描述,您可以创建 ApiInfoContact 对象,如下例所示。 然后,您只需将 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()));
  


上面的代码会产生如下截图所示的描述。

【讨论】:

我已添加您的图片 - 待审核...但您似乎在这里回答了另一个问题!问题是关于 @Api 注释的 description 属性 - 它是按类/标签/入口点组呈现的,而不是屏幕截图中的整个应用程序的 API【参考方案5】:

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

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

(*在我们的代码库中,使用干净的类和方法名称等,代码读者当然不需要这样的“API 描述”。我本来可以容忍代码库中出现这些与 Swagger 相关的噪音如果他们在 Swagger UI 中增加了一些价值,但既然他们没有,那么唯一明智的做法就是把它们扔掉。)

【讨论】:

【参考方案6】:

我发现以下工作是通过结合 @Api@Tag 注释构建的 this answer 来实现的。

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


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


【讨论】:

【参考方案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/");
    

【讨论】:

以上是关于不推荐使用 Api 注释的描述的主要内容,如果未能解决你的问题,请参考以下文章

htmlcss和js注释的规范用法

Java语言概述-注释与API文档等

java注释 命名 数据类型 基本类型转换 位运算符 逻辑运算符 三目运算符

Google Analytics,从 API 获取注释

注释生成Api文档

03-注释与API文档