我有一个用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中的所有请求定义自定义默认注释？或者使用某种过滤器来实现它？

解决方法:

快速浏览注释

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密钥是凭据.发送请求时,凭据值将在Authorization标头(或您定义的标头)中发送：

有关其他详细信息,请查看documentation.

只是一个快速的提示

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

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

XMLHttpRequest cannot load http://petstore.swagger.io/v2/pet/findByStatus?status=active. Request header field X-Auth-Token is not allowed by Access-Control-Allow-Headers in preflight response.