Generic Java Swagger Header

Question

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

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

Now I need to manually add the token as an ApiImplicitParam annotation to each of the requests so that the generated documents include it:

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

I don’t want to hardcode the user interface code to add the header itself, since I believe that it violated the encapsulation API provided by swagger.json . The server definition must contain all the details necessary for the generated documents.

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

Answer 1

Quick view annotations

ApiImplicitParam and ApiImplicitParams annotations are defined as follows:

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

Pay attention to @Target(value=METHOD) . This means that these annotations can only be applied to methods .

See the documentation for more details.

What Swagger UI Can Do For You

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

Take a look at index.html . The default implementation sends the API key as a request 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 an 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 that you entered in the credentials field. When sending a request, the credentials value will be sent in the Authorization header (or in the header you defined):

See the documentation for more information .

Just a quick hint

When testing the pet store example, make sure that the header you added matches the values ​​for the Access-Control-Allow-Headers header. For an example pet store, the allowed headers are Content-Type , api_key and Authorization .

Therefore, if you try to add the X-Auth-Token header in the pet store example, you will have the following error:

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