作者：Ole Lensmar
最近用于 Java 的 Swagger 核心工具为 Swagger 运行时使用的核心注解添加了许多功能，以便为您的 API 生成 Swagger 定义。让我们快速浏览一下这些功能，看看它们如何在您使用自下而上的方法创建 Swagger 定义时帮助您提供更完整的 API 元数据。
@SwaggerDefinition
@SwaggerDefinition 注解是核心注解中最大的新增功能；它为您提供了一种向生成的 Swagger 添加定义级元数据的方法，所有这些都直接与 Swagger 2.0 规范中的 Swagger 对象的属性相关联
- info - 提供关于整个 API 的元数据（标题、描述、许可证等）
- consumes - 此定义中描述的 API 使用的全局 MIME 类型列表
- produces - 此定义中描述的 API 生成的全局 MIME 类型列表
- schemes - 此 API 支持的传输协议
- basePath - 覆盖 Swagger 运行时推断出的 basePath
- host - 覆盖 Swagger 运行时推断出的 host
- tags - 规范使用的标签列表，带有其他元数据。
- externalDocs - 其他外部文档引用
该注解可以位于 Swagger 运行时扫描的任何类上。例如，您可以在项目中拥有一个仅具有此注解的空接口 - 以将一般 API 元数据与特定于 API 资源的元数据分开。例如，将其与标准 JAX-RS 资源放在一起
@SwaggerDefinition(
info = @Info(
description = "我的 API",
version = "V1.2.3",
title = "您了解我的唯一 API",
termsOfService = "共享和关爱",
contact = @Contact(name = "海绵宝宝", email = "[email protected]", url = "https://swagger.org.cn"),
license = @License(name = "Apache 2.0", url = "https://apache.ac.cn"),
consumes = {"application/json" },
produces = {"application/json" },
schemes = {SwaggerDefinition.Scheme.HTTP, SwaggerDefinition.Scheme.HTTPS},
externalDocs = @ExternalDocs(value = "关于我", url = "http://about.me/me")
)
public interface MyApiDefinition {}
导致将其添加到生成的 Swagger 定义中
{
"swagger": "2.0",
"info": {
"description": "我的 API",
"version": "V1.2.3",
"title": "您了解我的唯一 API",
"termsOfService": "共享和关爱",
"contact": {
"name": "海绵宝宝",
"url": "https://swagger.org.cn",
"email": "[email protected]"
},
"license": {
"name": "Apache 2.0",
"url": "https://apache.ac.cn"
},
"schemes": [
"http",
"https"
],
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"paths": {
...
您可以在 wiki 上阅读有关 SwaggerDefinition 注解的更多信息，以及其对应的 javadoc。
@Extension
扩展注解允许您向 Swagger 定义添加 扩展属性。目前在 @ApiOperation、@Info 和 @Tag 注解中支持。有两种使用方式
...
extensions = {
@Extension(properties = {
@ExtensionProperty(name = "test1", value = "value1"),
@ExtensionProperty(name = "test2", value = "value2")
})
}
...
这将导致以下 JSON
...
"x-test1" : "value1",
"x-test2" : "value2"
...
如果未在注解中明确执行此操作，则属性名称将自动添加前缀“x-”。
或者，您可以命名扩展
...
extensions = {
@Extension( name = "my-extension", properties = {
@ExtensionProperty(name = "test1", value = "value1"),
@ExtensionProperty(name = "test2", value = "value2")
})
}
...
这将导致以下 JSON
...
"x-my-extension" : {
"test1" : "value1",
"test2" : "value2"
}
...
这将包含的扩展属性包装在 JSON 对象中。
ReaderListener
如果这些注解扩展仍然无法帮助您按照您想要的方式制作 Swagger 定义，您可以选择创建一个 ReaderListener，它将在 Swagger 运行时之前和之后被调用。此扩展读取所有 Swagger 和 JAX-RS 注解并构建相应的 Swagger 定义。实现任一处理程序使您可以完全控制生成的定义，从而允许您以任何您想要的方式更改它
- 添加安全定义或自定义模型对象
- 基于某些上下文属性过滤掉不需要的信息
- 读取并添加在其他地方定义的 API 定义
- 等等。
您需要做的就是提供一个实现 ReaderListener 接口的类，并确保该类被 Swagger 运行时使用的类路径扫描器找到。如果您创建一个如上所示的 @SwaggerDefinition 注释接口，您可以将其更改为一个类并在其中实现此接口
@SwaggerDefinition(...)
public class MyApiDefinition implements ReaderListener {
public static final String TOKEN_AUTH_SCHEME = "tokenAuthScheme";
public static final String ACCOUNT_READ_SCOPE = "account_read";
public static final String ACCOUNT_WRITE_SCOPE = "account_write";
@Override
public void beforeScan(Reader reader, Swagger swagger) {
}
@Override
public void afterScan(Reader reader, Swagger swagger) {
OAuth2Definition tokenScheme = new OAuth2Definition();
tokenScheme.setFlow("password");
tokenScheme.setTokenUrl("https://" + swagger.getHost() + "/tokens");
Map<String, String> scopes = new HashMap<>();
scopes.put(ACCOUNT_READ_SCOPE, "读取我的数据");
scopes.put(ACCOUNT_WRITE_SCOPE, "更新我的数据");
tokenScheme.setScopes(scopes);
swagger.addSecurityDefinition(TOKEN_AUTH_SCHEME, tokenScheme);
}
}
此示例添加了一个 OAuth2 密码凭据授权安全定义，您可以在 @ApiOperation 注解中使用如下内容来引用它
@ApiOperation(value = "Updates user data",
authorizations = @Authorization(value = MyApiDefinition.TOKEN_AUTH_SCHEME, scopes =
@AuthorizationScope(scope = MyApiDefinition.ACCOUNT_WRITE_SCOPE, description = "对用户数据的写入访问")))
public Response updateUser( UserData data ) throws NotFoundException {
...
}
由于 ReaderLicenser 特定于 Swagger Core 项目中的 JAX-RS 实现模块，因此它在 io.swagger.swagger-jaxrs 模块中可用，而不是像上面描述的其他模块一样在 io.swagger.swagger-annotations 中可用。
对注解的更多改进
以上不是对 Swagger 注解进行的唯一改进和添加 - 我们还
与往常一样 - 如果您缺少某些内容或发现问题 - 请在 Google Group 或 GitHub 上联系我们，以便我们可以解决问题并使 Swagger 变得更好！