Using Swagger Documents¶
API documentation is important to guide the users on what they can do using specific APIs. Follow the steps given below to use the Swagger documentation of your REST API artifacts.
Swagger definition of a REST API¶
When you create a REST API artifact from WSO2 Integration Studio, a default Swagger definition is generated. You can also attach an additional custom Swagger definition for the API.
See Creating a REST API for details.
Enabling the Swagger processors¶
To expose the Swagger documents of REST APIs deployed in the Micro Integrator:
First, add the following server configurations to the
deployment.tomlfile (stored in the
<MI_HOME>/confdirectory) of the Micro Integrator.
[[server.get_request_processor]] item = "swagger.json" class = "org.wso2.micro.integrator.transport.handlers.requestprocessors.swagger.format.SwaggerJsonProcessor" [[server.get_request_processor]] item = "swagger.yaml" class = "org.wso2.micro.integrator.transport.handlers.requestprocessors.swagger.format.SwaggerYamlProcessor"
The above configuration enables two Swagger processors:
SwaggerJsonProcessorprovides access to the Swagger documentation as a JSON file (
SwaggerYamlProcessorprovides access to the Swagger documentation as a YAML file (
Restart the server to apply the configurations.
Accessing Swagger docs¶
If you have enabled the Swagger processors in your server, and if your REST API is deployed, copy the following URLs (with your API details) to your browser:
If you have a custom Swagger definition attached to the API, the following URLs will return the custom definition and not the default Swagger definition of the API.
To access the
swagger.jsonfile, use the following URL:
To access the
swagger.yamlfile, use the following URL:
localhost. If you are using a public IP, the respective IP address or domain needs to be specified.
<API_NAME>with your API's name. The API name is case sensitive. Therefore, make sure to enter the API name correctly.