Swagger Java常用标题 [英] Swagger Java common header

问题描述

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

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

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

  @ApiImplicitParams（{@ ApiImplicitParam（name = AuthFilter.AUTHORIZATION_PROPERTY，value =授权令牌， required = true，dataType =string，paramType =header）}）
  

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

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

解决方案

A快速查看注释

的Swagger UI页面标题

查看

有关其他详细信息，请参阅查看文档。

只是一个快速提示

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

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

XMLHttpRequest无法加载 http：//petstore.swagger。 IO / V2 / PET / findByStatus？状态=活性。预检响应中 Access-Control-Allow-Headers 不允许使用请求标头字段 X-Auth-Token 。 / p>

I have a REST API server implemented with Jersey2.0 and integrated with Swagger to automate docs and client side applications.

We have our own authentication header (X-Auth-Token) which should be applied to all requests in order to use them (Beside the login request that retrieves the token if credentials are correct).

Right now I need to manually add the the token as ApiImplicitParam annotation to each of the requests in order for the generated docs to include it:

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

I don't want to hardcode the UI code to add the header itself, as I believe it violated the API encapsulation provided by swagger.json. The server definition should provide all the details necessary for the generated docs.

Is there a way to define a custom default annotation for all requests in Swagger? Or alternatively use some kind of Filter to achieve it?

解决方案

A quick look at the annotations

The ApiImplicitParam and ApiImplicitParams annotations are defined as following:

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

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

Please note the @Target(value=METHOD). It means these annotations only can be applied to methods.

For more details, check the documentation.

What Swagger UI can do for you

In Swagger UI version 2.1.4 released on 6th January 2016 (the most recent version when this answer was written), you can have an API key:

Have a look at the index.html. The default implementation sends the API key as a query parameter:

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);
    }
}

But you can change it to send a HTTP header:

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);
    }
}

Consider, for example, the API key you've entered in the box is credentials. When sending the request, the credentials value will be sent in the Authorization header (or in the header you've defined):

For additional details, have a look the documentation.

Just a quick hint

When testing the pet store example, ensure the header you've added matches with the values of the header Access-Control-Allow-Headers. For the pet store example, the allowed headers are Content-Type, api_key and Authorization.

Hence, if you try adding the X-Auth-Token header in pet store example, you'll have the following error:

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.

这篇关于Swagger Java常用标题的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！