Open API 3.0 Support In WSO2 API Manager

WSO2 API Manager is an open source API Management platform to manage APIs in your organization while enforcing API security, managing API traffic, and analytics. The previous releases of API Manager have been supporting Swagger 2.0 for API templating. But from WSO2 API Manager 2.2.0 release onwards, Open API 3.0 specification support is available for designing, importing, visualizing APIs, along with Open API 2.0/Swagger 2.0 support as well.

With this new feature, you can

  • Import existing Open API 3.0 API definition and expose it as an API in APIM
  • Designing an Open API 3.0 specification supported API in APIM
  • Advanced editing of OAS 3.0 API source in Swagger Editor
  • Try out OAS 3.0 APIs in API console
  • Download Open API 3.0 based API definitions

Importing an existing OAS 3.0 API into API Manager

If you already have an Open API 3.0 based API definition, it can be directly imported and exposed through API Manager.

Please follow below steps to import an existing OAS 3.0 API into API Manager.

  • Login to API Publisher (https://localhost:9443/publisher)
  • Start creating an API by clicking ‘Add New API’ button.
  • Once you have navigated to Add New API page, different options of creating an API will be shown in the API create page. In order to import an existing OAS 3.0 definition, you need to select ‘I have an Existing API’ option. API Publisher allows you to import API definitions in both yaml and json formats. The API definition can be provided either as a file content or a URL content. When the OAS 3.0 definition source is provided, click on ‘Start Creating’ button to import the API.
  • When API definition is imported, the content will be validated against OAS 3.0 specification. If the content is valid and complies with OAS 3.0 spec, the definition will be successfully imported and API metadata(name, description, version)and resource definitions will be populated accordingly. If the definition is invalid, you will be notified with the syntax error.
General details populated from OAS 3.0 definition
  • Most importantly, the imported API definition is used to auto-generate the API resources. The URI templates, parameters(query, path and header parameters), request body content etc will be populated as per the OAS definition. Imported API’s path definitions will be populated in API resource UI as follows.
GET Resource definition
POST Resource definition
  • Then click on ‘Next: Implement’ button and you will be navigated to API Implement phase. Fill the endpoint details in Implement phase and click on ‘Next: Manage’ button to go to API Manage tab.
  • The fill the details in API Manage phase and click on Save and Publish button to publish the API to API Store.

Designing an Open API 3.0 specification supported API in APIM

API Manager facilitates designing a new API from scratch. When designing the API, corresponding OpenAPI/Swagger definition is generated underneath including the metadata and resources you define in API design, manage and implement phases. From APIM 2.2.0 onwards, you can select the supported Open API specification version. By default, API Manager supports both OAS 3 and OAS 2 versions.

Following steps shows how to design an OAS 3.0 supported API from scratch.

  • Login to API Publisher (https://localhost:9443/publisher)
  • Start creating an API by clicking ‘Add New API’ button.
  • Then you will be navigated to API create options page and select ‘Design New API’ option to design a new API. By default, newly designed APIs are supported by OAS 2.0, but in order to switch the OAS spec version, click on Show More link and select the ‘OpenAPI 3.0’ from the drop down.
To select supported OAS specification version
  • Once the OAS spec version is selected, you can click on ‘Start Creating’ button to continue with API creation. The API definition generated underneath will be supporting the selected API specification.

Advanced editing of OAS 3.0 API source in Swagger Editor

For advanced/complex editings of the API source, you can use the embedded Swagger Editor, which comes with OAS 3.0 support. The Swagger Editor can be used to directly access the API spec, easily edit the API definition, apply advanced config changes, validate them, generate server stubs and client libraries for both OpenAPI 3.0 and OpenAPI 2.0 spec supported APIs.

Swagger Editor, which has been shipped with API Manager can be accessed in API design page.

To edit an API in embedded Swagger editor,

  1. Go to API create or edit pages and navigate to API design tab
  2. Click edit source to access the Swagger Editor.
  1. You will be navigated to swagger editor.
  1. Edit the API in Swagger editor. The changes will be validated on fly and validation failures will be notified in the right side of the editor, if there are any syntax errors.
  1. After applying the changes, click ‘Apply Changes’ to persist the changes done.

Try out OAS 3.0 APIs in API console

In API Manager Store comes with a try-out tool to visualize, invoke and try out the Published APIs in API Store. The latest Swagger UI which supports for OAS 3.0 and OAS 2.0 has been embedded in API Store as the try out tool. Hence API consumers can use the API console to visualize the API and available resources, switch gateway environments, effortlessly interact and try out with every single operation your API exposed for external consumption.

To try out an API in API Store,

  • Click and expand the resource you want to try out. Then click ‘Try Out’ button
  • Fill required parameter values, or payloads and click ‘Execute’. Then you can observe the response with response message and response codes.

Download API source in OAS 3.0

The Open API definition of each REST API can be downloaded from API Publisher and Store apps.

To download API source, you have to navigate to API overview page in API Publisher and click ‘Download Source’ button.