Month: February 2018

Set Request Headers in Swagger-UI

For the last 2 days, I was facing a issue with setting Global Request headers to Springfox’s Swagger-UI (version 2.8.0) for a SpringBoot Application.

The issue was more related to the new Swagger version 2.8.0 and does not any issues in prior versions. In the below code, I am only presenting the cause and the solution. Assuming the developers have prior knowledge of Swagger and its implementation. More implementation details can be found at https://springfox.github.io/springfox/docs/current/#quick-start-guides

@Bean
    public Docket apiSwaggerDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                .paths(PathSelectors.any())
                .build()
                .pathMapping("/")
                .genericModelSubstitutes(ResponseEntity.class)
                .useDefaultResponseMessages(false)
                .forCodeGeneration(true)
                .securitySchemes(newArrayList(apiKey()))
                .apiInfo(apiInfo());

    private ApiKey apiKey() {
        return new ApiKey("access_token", "access_token", "header");
    }

Let’s only concentrate on the apiKey() method. The new ApiKey(…) constructor has different argument signatures for different versions of springfox’s swagger.

/**
* http://springfox.github.io/springfox/javadoc/current/springfox/documentation/service/ApiKey.html
* Signature of the ApiKey constructor
* return new ApiKey(name, keyName, passAs);
* 
* name - is the name of the key
* keyName - is the value of the key name
* passAs - you can pass as header or query parameter
*/
// For version 2.6.0
return new ApiKey("Authorization", "Bearer", "header");

Output at swagger-ui
name: Authorization
in: header
value: Bearer

// For version 2.7.0 - This version has reverse the constructor Argument signature
return new ApiKey("Authorization", "Bearer", "header");

Output at swagger-ui
name: Authorization
in: header
value: Bearer

// For version 2.8.0
return new ApiKey("Authorization", "Bearer", "header");

Output at swagger-ui
There is no header displayed in this version of the swagger.

For my current use case, I had to step down the swagger version to 2.7.0.

Alternatively, if one intends to use version 2.8.0, we can have globalOperationParameters to put in use, with all API’s requesting for header

@Bean
    public Docket apiSwaggerDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                .paths(PathSelectors.any())
                .build()
                .pathMapping("/")
                .genericModelSubstitutes(ResponseEntity.class)
                .useDefaultResponseMessages(false)
                .forCodeGeneration(true)
                .apiInfo(apiInfo())
                .globalOperationParameters(
                        newArrayList(new ParameterBuilder()
                                .name("access_token")
                                .description("Access Token")
                                .modelRef(new ModelRef("string"))
                                .parameterType("header")
                                .required(true)
                                .build()));
    }

The only drawback using globalOperationParameters, the header is not sticky. Meaning, the same header value is required for each and every API in Swagger, which is not great.

Thanks for reading my post 🙂

More Reading & Resources:

Forward Proxy vs Reverse Proxy

proxies

Forward Proxy Reverse Proxy
Processes Outgoing Requests Processes Incoming Requests
A Forward Proxy is just called a Proxy. When Someone says a proxy, that just means a forward proxy. An example of a forward proxy would be, for example if you work at a big firm, where there are a lot of computers/employees making a request to the same website to go get some information, (an example could be a LDAP server where the backed end service to it gets called most frequently), so this company may setup a forward proxy, so all the employees may send request to this forward proxy, which can do a bunch of things before it forwards the request to the server or a reverse proxy if it has one setup. Even though the server instances endpoints keep changing, the client endpoints remain same. Reverse proxy handles the incoming requests and delegates it to the server instances, even though the server instances scales up or down or if any server node instances fail.
The reverse proxy handles a stable endpoint at the start (before it receives a incoming request), so the client endpoint does not change.
The reverse proxy hides or shield’s the server instances from incoming traffic.
How does the reverse proxy decide to which server instance to route?
A forward proxy can do Content Filtering. May be a administrator at the company has setup up a forward proxy to stop certain malicious, censored, gambling or translation website traffic from coming in to the internal servers or to the internet traffic (external) from going out. A forward proxy acts as the first shield of defence. Reverse Proxy can be used as Load Balancers. There are 2 types of Load Balancers Level 4 & Level 7.
Level 4 Load Balancers can handle UDP/TCP traffic. It’s level 4 because of OSI networking model. They handle traffic by tapping at level 4 of OSI networking model.
Level 7 Load Balancers handle HTTP/HTTPS incoming traffic. It’s Level 7 because it is level 7 in the OSI networking model, which is the Application layer. It can look at URI’s, HTTP Headers. The HTTP Headers can also direct which server instance to direct to.
Also, with Reverse Proxy as a Load Balancer, you can do Server selection, A/B Testing, meaning you can dictate the reverse proxy configuration to direct the traffic based on the amount of incoming traffic load. Example, you can configure it to go to server instance 1 if the incoming traffic is > 10% and go to server instance 2 if the incoming traffic is < 10%
Forward proxy can be used for Caching. It can return the same content to different employees when a request comes in, so it can save a lot of money to the client, by reducing its bandwidth usage, because the cached request does not use the internet. Reverse Proxy can be used as a SSL Termination, where the SSL certificate get authenticated (from the very first request coming the Client side, i.e HTTPS (encrypted)) and all the incoming traffic routing to server instances thereafter can all be just HTTP (non encrypted) instead of HTTPS (encrypted)
A Forward proxy can be used for Logging & Monitoring. Like, may be the company wants to know when the employees are coming to office or what websites are being used frequently or how much data people are downloading. So, all these metrics can be used to better fine tune its internet infrastructure & offices. like may be they need more routers or better wifi signal capability or wired routers. Reverse Proxy can be used for Caching Purpose as well. The very first request can be cached for the later requests, which the reverse proxy can send out. This eventually can save lot of incoming traffic load and a lot of money for the prospective clients.
A forward proxy can be used as Client Anonymization. Meaning, the forward proxy can send less information to the server, like hide the clients information before sending out the request to server. This way the clients feel much secure, that they are not being tracked or stored any of their location or identity information to server. Reverse Proxy can be used to do Authentication & Validation. Like the first incoming request from the client may send some authorization information in HTTP Header and may send some cookie information and then the reverse proxy may authenticate it and then send the request to its server instances just to fetch data.
 Forward proxy sits right in front of the firewall, which blocks outgoing traffic to server. Reverse Proxy can be used to do Tenant Throttling and billing. For example, if some user tampers with a request, lets a say a 1000 requests per second, the reverse proxy can detect this type of requests and can then block it right away and so the server instances doesn’t have to worry about throttling, accounting or bookkeeping. Also since some B2B services get billed for every request that comes in, the reverse proxy can identify the individuals and increment the billing counter for their sent requests and send a monthly incurred billing stats.
Some reverse proxies use Distributed Denial of Service (DDoS) Attacks mitigation. If the reverse proxy sees a lot of requests coming from one single client, then it can stop the requests for about an hour or the next day, so each of the server instances doesn’t need to worry about DDoS attacks.

Source: