不推荐使用 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】:我尝试了上述解决方案,但它们对我不起作用。
要为文档添加标题和描述,您可以创建 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()));
上面的代码会产生如下截图所示的描述。
【讨论】:
我已添加您的图片 - 待审核...但您似乎在这里回答了另一个问题!问题是关于@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 注释的描述的主要内容,如果未能解决你的问题,请参考以下文章