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.
API Console keeps on loading the response for ever as below.
API resource not supporting OPTIONS HTTP verb.
Add OPTIONS HTTP verb for API resources as below. Then Save the API and Try again.
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.
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.
API Console completes request execution, but no response is returned.
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
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.
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.
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.
API Console keeps on loading the response for ever as below when API Store is accessed as HTTPs, while HTTP is working properly.
Browser blocking the request due to accessing the API Gateway in HTTP from HTTPs.
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.
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.
Access the HTTPS gateway endpoint directly from your browser and accept the security certificate. Then try again.