Swagger Java常用标题

Question

我有一个使用Jersey2.0实现的REST API服务器，并与Swagger集成以自动化文档和客户端应用程序。

我们有自己的身份验证标头（X-Auth-Token），应该将其应用于所有请求以便使用它们（如果凭据正确，则会在检索令牌的登录请求旁边）。

现在我需要手动将令牌添加为ApiImplicitParam注释到每个请求，以便生成的文档包含它：

@ApiImplicitParams({@ApiImplicitParam(name = AuthFilter.AUTHORIZATION_PROPERTY, value = "Authorization token", required = true, dataType = "string", paramType = "header")})

我不想硬编码UI代码来添加标头本身，因为我认为它违反了swagger.json提供的API封装。服务器定义应提供生成的文档所需的所有详细信息。

有没有办法为Swagger中的所有请求定义自定义默认注释？或者使用某种Filter来实现它？

Answer 1

快速查看注释

ApiImplicitParam和ApiImplicitParams注释定义如下：

@Target(value=METHOD)
@Retention(value=RUNTIME)
public @interface ApiImplicitParam

@Target(value=METHOD)
@Retention(value=RUNTIME)
public @interface ApiImplicitParams

请注意@Target(value=METHOD)。这意味着这些注释只能应用于方法。

有关详细信息，请查看documentation。

Swagger UI可以为您做什么

在2016年1月6日发布的Swagger UI版本2.1.4中（编写此答案时的最新版本），您可以拥有API密钥：

查看index.html。默认实现将API密钥作为查询参数发送：

function addApiKeyAuthorization(){
    var key = encodeURIComponent($('#input_apiKey')[0].value);
    if(key && key.trim() != "") {
        var apiKeyAuth = new SwaggerClient.ApiKeyAuthorization("api_key", key, "query");
        window.swaggerUi.api.clientAuthorizations.add("api_key", apiKeyAuth);
        log("added key " + key);
    }
}

但您可以将其更改为发送HTTP标头：

function addApiKeyAuthorization(){
    var key = encodeURIComponent($('#input_apiKey')[0].value);
    if(key && key.trim() != "") {
        swaggerUi.api.clientAuthorizations.add("key", 
            new SwaggerClient.ApiKeyAuthorization("Authorization", key, "header"));
        log("added Authorization header " + key);
    }
}

例如，请考虑您在框中输入的API密钥为credentials。发送请求时，credentials值将在Authorization标题中（或您已定义的标题中）发送：

有关其他详细信息，请查看documentation。

只是一个快速提示

在测试宠物商店示例时，请确保您添加的标题与标题Access-Control-Allow-Headers的值匹配。对于宠物商店示例，允许的标头为Content-Type，api_key和Authorization。

因此，如果您尝试在宠物商店示例中添加X-Auth-Token标题，则会出现以下错误：

  

XMLHttpRequest无法加载http://petstore.swagger.io/v2/pet/findByStatus?status=active。预检响应中X-Auth-Token不允许请求标题字段Access-Control-Allow-Headers。