Troubleshooting Swagger issues in WSO2 API Manager

WSO2 API Manager provides this functionality through the integration of Swagger (https://developers.helloreverb.com/swagger). Swagger-based interactive documentation allows you to try out APIs from the documentation itself which is available as the "API Console" in API Store. 

There are certain requirements that need to be satisfied in order to swagger Try-it functionality to work. First requirement is to enable CORS in API Mananger Store. This documentation describes how that should be done. 

But most of them face many issues in getting the swagger Try-it into work. So this blog post describes common issues faced by users with Swagger and how to troubleshoot them.  

Issue-1

API Console keeps on loading the response for ever as below.

Cause -1

API resource not supporting OPTIONS HTTP verb. 

Solution

Add OPTIONS HTTP verb for API resources as below. Then Save the API and Try again. 



Cause -2 

Backend endpoint not supporting OPTIONS HTTP verb. 

Note: You can verify this by directly invoking the backend for OPTIONS verb. If backend is not supporting OPTIONS verb, "403 HTTP method not allowed" will be returned. 

Solution

If you have control over the Backend service/api, enable OPTIONS HTTP verb. 

Note: You can verify this by directly invoking the backend for OPTIONS verb. If backend is supporting OPTIONS verb, 200/202/204 success response should be returned.


If you can't enable OPTIONS HTTP verb in the backend, then what you can do is modify the API synapse sequence of the API, which returns back without sending the request to the backend if it is an OPTIONS request. 

Issue-2

API Console completes request execution, but no response is returned. 


Cause-1

Authentication Type enabled for OPTIONS HTTP verb is not 'None'. 


If this is the cause below error message will be shown in the wso2carbon.log.

org.wso2.carbon.apimgt.gateway.handlers.security.APISecurityException: Required OAuth credentials not provided
at org.wso2.carbon.apimgt.gateway.handlers.security.oauth.OAuthAuthenticator.authenticate(OAuthAuthenticator.java:122)
at org.wso2.carbon.apimgt.gateway.handlers.security.APIAuthenticationHandler.handleRequest(APIAuthenticationHandler.java:92)
at org.apache.synapse.rest.API.process(API.java:285)
at org.apache.synapse.rest.RESTRequestHandler.dispatchToAPI(RESTRequestHandler.java:83)
at org.apache.synapse.rest.RESTRequestHandler.process(RESTRequestHandler.java:64)
at org.apache.synapse.core.axis2.Axis2SynapseEnvironment.injectMessage(Axis2SynapseEnvironment.java:220)
at org.apache.synapse.core.axis2.SynapseMessageReceiver.receive(SynapseMessageReceiver.java:83)
at org.apache.axis2.engine.AxisEngine.receive(AxisEngine.java:180)
at org.apache.synapse.transport.passthru.ServerWorker.processNonEntityEnclosingRESTHandler(ServerWorker.java:344)
at org.apache.synapse.transport.passthru.ServerWorker.run(ServerWorker.java:168)
at org.apache.axis2.transport.base.threads.NativeWorkerPool$1.run(NativeWorkerPool.java:172)
at java.util.concurrent.ThreadPoolExecutor$Worker.runTask(ThreadPoolExecutor.java:895)
at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:918)
at java.lang.Thread.run(Thread.java:662)

Solution

Make the Auth Type as none for OPTIONS HTTP verb as below. Then Save & Publish the API.



Note: If you are seeing the Issue -2 , even though Authentication type is shown as none for OPTIONS, then please re-select the authentication type as 'none' as above. Then Save & Publish the API. There is an UI bug in API Manager 1.7.0, where although you have set some other authentication type other than 'None' for OPTIONS verb, UI shows it as none. 

Cause-2

API Store domain/port which you are currently trying swagger API Console, is not included in the CORS Access-Control-Allow-Origin configuration. For example, in below CORS configuration, only localhost domain addresses are allowed for API Store. But API Console is accessed using IP address. 




Solution

Include domain/port in the CORS Access-Control-Allow-Origin configuration. For above example, we have to include IP address as below.  Then restart the server and try API Console again. 


Issue-3

API Console keeps on loading the response for ever as below when API Store is accessed as HTTPs, while HTTP is working properly. 

Cause-1

Browser blocking the request due to accessing the API Gateway in HTTP from HTTPs. 

Solution

Go to API Publisher and edit "Swagger API Definition" of the API and change the basePath with https gateway address as below. The Save the "Swagger API Definition" and try again. 


Cause-2 

If you are still getting the issue, even after applying the above then, cause can be that the security certificate issued by the server is not trusted by your browser.

Solution

Access the HTTPS gateway endpoint directly from your browser and accept the security certificate. Then try again. 


Comments

  1. AnthonyJanuary 10, 2015 at 8:05 AM

    Thanks for the great post. I am using version 1.8 of the API Manager and I am having an issue with the try-it functionality. I did all the things you recommended but when I click on Try It, I am getting no response. I have CORS enabled and OPTIONS has None for authorization. I also have HTTPs working. In Firebug, the console has a 403 error for the OPTIONS call. I did notice that the headers for the OPTIONS request had an Access-Control-Request-Header of 'authorization'. If I make a similar request with a different tool, I also get a 403 error. Removing the header fixes the issue. Is this a bug or do you think I have something setup incorrectly? Thanks for any advice.

    ReplyDelete
  2. LakmaliJanuary 16, 2015 at 11:04 PM

    Can you do a OPTIONS call to your API URL as below and post your responses here?

    ex:- curl -v -X OPTIONS http://localhost:8280/api/1.0.0

    ReplyDelete
  3. AnthonyJanuary 17, 2015 at 12:48 AM

    Thanks for responding. Here is the response from curl -v -k -X OPTIONS https://dev.xxxx.com:8243/pub/vp/1.0.0/members

    > OPTIONS /pub/vp/1.0.0/members HTTP/1.1
    > User-Agent: curl/7.19.7 (x86_64-redhat-linux-gnu) libcurl/7.19.7 NSS/3.14.3.0 zlib/1.2.3 libidn/1.18 libssh2/1.4.2
    > Host: dev.xxxx.com:8243
    > Accept: */*
    >
    < HTTP/1.1 200 OK
    < Access-Control-Allow-Headers: authorization,Access-Control-Allow-Origin,Access-Control-Request-Headers,Content-Type
    < Last-modified: Fri, 16 Jan 2015 09:07:31 EST
    < Allow: POST,GET,OPTIONS,HEAD,PUT
    < Access-Control-Allow-Methods: GET,PUT,POST,DELETE,OPTIONS
    < Content-Type: application/vnd.sun.wadl+xml
    < Date: Fri, 16 Jan 2015 14:07:31 GMT
    < Server: WSO2-PassThrough-HTTP
    < Transfer-Encoding: chunked
    <

    Here are the headers for the OPTIONS request sent by the browser when I click on the OPTIONS try-it button:

    OPTIONS /pub/vp/1.0.0/members HTTP/1.1
    Host: dev.xxxx.com:8243
    User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:34.0) Gecko/20100101 Firefox/34.0
    Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
    Accept-Language: en-US,en;q=0.5
    Accept-Encoding: gzip, deflate
    Origin: https://dev.xxxx.com:9443
    Access-Control-Request-Method: OPTIONS
    Access-Control-Request-Headers: authorization
    Connection: keep-alive

    Here is the equivalent curl request and the response:
    curl -v -k -X OPTIONS -H 'Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8' -H 'Accept-Encoding: gzip, deflate' -H 'Accept-Language: en-US,en;q=0.5' -H 'Access-Control-Request-Headers: authorization' -H 'Access-Control-Request-Method: OPTIONS' -H 'Connection: keep-alive' -H 'Host: dev.xxxx.com:8243' -H 'Origin: https://dev.xxxx.com:9443' -H 'User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:34.0) Gecko/20100101 Firefox/34.0' 'https://dev.xxxx.com:8243/pub/vp/1.0.0/members'

    > OPTIONS /pub/vp/1.0.0/members HTTP/1.1
    > Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
    > Accept-Encoding: gzip, deflate
    > Accept-Language: en-US,en;q=0.5
    > Access-Control-Request-Headers: authorization
    > Access-Control-Request-Method: OPTIONS
    > Connection: keep-alive
    > Host: dev.xxxx.com:8243
    > Origin: https://dev.xxxx.com:9443
    > User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:34.0) Gecko/20100101 Firefox/34.0
    >
    < HTTP/1.1 403 Forbidden
    < Access-Control-Allow-Headers: authorization,Access-Control-Allow-Origin,Access-Control-Request-Headers,Content-Type
    < Access-Control-Allow-Origin: https://dev.xxxx.com:9443
    < Access-Control-Allow-Methods: GET,PUT,POST,DELETE,OPTIONS
    < Content-Type: text/plain
    < Date: Fri, 16 Jan 2015 14:05:08 GMT
    < Server: WSO2-PassThrough-HTTP
    < Transfer-Encoding: chunked
    < Connection: keep-alive
    <

    If I remove the Access-Control-Request-Headers headers from the OPTIONS request, this is the response:
    > OPTIONS /pub/vp/1.0.0/members HTTP/1.1
    > Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
    > Accept-Encoding: gzip, deflate
    > Accept-Language: en-US,en;q=0.5
    > Access-Control-Request-Method: OPTIONS
    > Connection: keep-alive
    > Host: dev.xxxx.com:8243
    > Origin: https://dev.xxxx.com:9443
    > User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:34.0) Gecko/20100101 Firefox/34.0
    >
    < HTTP/1.1 200 OK
    < Access-Control-Allow-Headers: authorization,Access-Control-Allow-Origin,Access-Control-Request-Headers,Content-Type
    < Access-Control-Allow-Origin: https://dev.xxxx.com:9443
    < Access-Control-Max-Age: 1800
    < Access-Control-Allow-Methods: GET,PUT,POST,DELETE,OPTIONS
    < Content-Type: application/octet-stream
    < Access-Control-Allow-Credentials: true
    < Date: Fri, 16 Jan 2015 14:10:34 GMT
    < Server: WSO2-PassThrough-HTTP
    < Transfer-Encoding: chunked
    < Connection: keep-alive
    <

    ReplyDelete
  4. BazookaFebruary 12, 2015 at 8:06 PM

    Thanks for the informative post.

    I tried adding OPTIONS HTTP verb to API resource. However, when I press submit button after adding the verb, I get a message 'Error while adding the API - '

    ReplyDelete

Post a Comment

Popular posts from this blog

PHP-SOAP web service with out a WSDL

This article is going to describe how to create a simple web service with php-soap step by step. Requirements     Server to run php (apache, xampp , wamp)     PHP-SOAP extension Steps Let's write a simple web service to find the length of a given string. So here is the code for StringLengthServer.php   <?php # StringLengthServer.php # Copyright (c) 2011 by Lakmali Baminiwatta #     function findLength($string) {            return "Length of the string " . $string . "is : ".strlen($string);     }            $server = new SoapServer(null,               array('uri' => "urn://www.lakmali.lk"));        $server->addFunction("findLength");        $server->handle();  ?> First thing done here is to write a function to perform the action done by the service. So here function findLength($string) takes a string as the argument and prints back the length of it. Then SoapServer is created. First argument
Keep reading

Boomi Mapping - Removing special chars from an input

Image
Dell Boomi mapping shape provides numerous ways to modify/enrich an input via functions. In this post I am going to show how I validated and removed special chars from an input using Scripting and do it along with another string function. The user defined functions available with mapping, allows us to apply sequence of functions to the input. In this example, I am going to use it. Use Case: I have two input strings coming from the source profile (first_name and last_name), which I want to first concatanate together and then remove non-alphanumeric characters if present. Solution In your map, add an User Defined function and add two inputs; first_name, last_name.  Add User Defined function into the map Added inputs to the user defined function As the first step, add a function "String Concat" under the  "String" category.  Specify first_name and last_name as the inputs. Also set a delimiter, if you need a one. In my case, I want to concatena
Keep reading

How to add Maven dependency from a relative path referencing a local jar

When you want to add a dependency which is not stored in maven repositories to your project this is the way!! You can manually download it and include inside the project and refer it from the pom.xml through a relative path. This example assumes that you have downloaded and stored the jar inside ${project}/src/test/resources/lib.  <dependency> <groupId>ojdbc</groupId> <artifactId>ojdbc6</artifactId> <scope>system</scope> <version>6</version> <systemPath>${basedir}/src/test/resources/lib/ojdbc6.jar</systemPath> </dependency> Here we must specify the scope of the dependency  as 'system'. There is another way which is to manually install the maven dependency to your local repository. You can find out how from here .
Keep reading