作者：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 运行时推断的基本路径
- host - 覆盖 Swagger 运行时推断的主机
- tags - 规范使用的标签列表，附带额外的元数据。
- externalDocs - 额外的外部文档引用
该注解可以放置在 Swagger 运行时扫描的任何类上。例如，您的项目中可以有一个只带有此注解的空接口，以将通用 API 元数据与特定于 API 资源的元数据分开。例如，将此注解与标准的 JAX-RS 资源放在一起：
@SwaggerDefinition(
info = @Info(
description = "我的 API",
version = "V1.2.3",
title = "您需要了解的关于我的唯一 API",
termsOfService = "分享与关爱",
contact = @Contact(name = "海绵宝宝", email = "[受电子邮件保护]", 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": "[受电子邮件保护]"
},
"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 {
...
}
由于 ReaderListener 特定于 Swagger Core 项目中的 JAX-RS 实现模块，因此它在 io.swagger.swagger-jaxrs 模块中可用，而不是像上面描述的其他模块一样在 io.swagger.swagger-annotations 中。
注解的更多改进
以上并非对 Swagger 注解的唯一改进和新增——我们还：
一如既往——如果您缺少某些功能或发现问题——请在 Google Group 或 GitHub 上与我们联系，以便我们解决问题，让 Swagger 变得更好！