In a world full of APIs we need to have a way to understand the functionality and meaning of an API before we can start using it. In the Oracle Cloud world (SaaS, PaaS and IaaS) all (or at least most) APIs are defined as REST services, based upon a JSON structure.
Since there is no conformed standard between API delivering parties, different design frameworks are used, with OpenAPI Specification (Swagger), RAML and API Blueprint the most popular ones. Oracle is opting for the OpenAPI Specification, with the accompanying design tool Swagger, as the standard for their products.
Oracle combined all the tools and resources for Cloud and On-prem software in a developers website. On this website the API descriptions for all PaaS products can be found. Unfortunately the information provided in the API overviews are pretty minimal. The online Swagger editor is not helping either, with all sorts of warnings popping up. The Swagger locally used UI tool requires CORS enabled calls, so out-of-the-box is offering the support we need.
This blogpost is about adding the last step in order to get insight in the Oracle PaaS API definitions with the Swagger UI tool. With the help of NodeJS CORS is added to the PaaS API call, and delivers the insight we want! 
OpenAPI specification and Swagger
The OpenAPI specification is described on the http://swagger.io/specification/ website and unfolds how both design elements and documentation are used to define an API. The entire structure of the API design is based upon JSON, though also YAML can be used as the underpinning language. Swagger supports this specification with a bunch of tools, that can be used both in-line and locally installed.
The Oracle Developer Gateway
As said, all information about Cloud and on-prem products are now combined through one website, the Oracle Developer Gateway.
Drilling down towards Documentation – Cloud – Platform – Content and Collaboration – Process shows all the resources for instance for the Process Cloud Services (PCS)
On the left hand side in the menu a link is provided towards the REST API’s
This picture also shows a specific API call that can be made to retrieve a Process Instance. The information about Request/Response is there, but it is minimal.
On-line Swagger editor
Let us open now the PCS API specification in the on-line Swagger tool. First we need to have the URL towards the PCS API specification This can be found by clicking on the Download button in the menu on the left side. By hoovering over the Swagger button the endpoint is revealed.
http://docs.oracle.com/cloud/latest/process_gs/CPRRA/swagger.json.
Now let’s use this URL to open the specification in the Swagger on-line editor.
When this URL is opened directly it is visible that the Swagger Editor is not able to deal with the way the Oracle PaaS API’s are defined. So time to move on towards another option for showing the API specs, the Swagger local UI.
Swagger local UI
Swagger delivers a set of tools to work with and on the API specification on http://swagger.io/tools/. One of them is the Swagger User Interface.
When the link is clicked you enter the download page, where (after clicking on Download) the usage of the Swagger User Interface is described.
Specifically look at the last remark in the usage description. In my opinion it makes no sense to require CORS for a tool that only shows the API description. But of course I’m open for discussion.
Note: Please remember that to load a specification and execute the UI’s try out requests, you would need to have enabled CORS (read below)
..
The method of enabling CORS depends on the server and/or framework you use to host your application. http://enable-cors.org provides information on how to enable CORS in some common web servers. Other servers/frameworks may provide you information on how to enable it specifically in their use case.
When the Swagger UI is downloaded and we try to open the Process Cloud API here the following error is received.
Getting the Swagger local UI to work
The idea here is to download the specific API (here again I will use the Process Cloud API), and deliver via a NodeJS based small webserver a CORS enabled API that can be used in the Swagger UI.
(1) First install NodeJS and NPM.
Go to https://nodejs.org for more details on this topic
(2) Download the small NodeJS project I created from Github.
(3) Initialise the project
Install the required Node module by running npm init from the command line
(4) Download the Process Cloud API, and place the Swagger file in the public directory in the NodeJS project. You might want to rename the JSON file towards and appropriate name, for instance PCS-swagger.json
(5) Start the NodeJS project
Open the command line, go to the NodeJS project and run node index.js
The Process Cloud API (the Swagger file we just downloaded) can now be opened in a browser with http://localhost:8081/PCS-swagger.json
(6) Now open the Swagger UI Tool
Open a browser and open the file [Swagger UI location]/dist/index.html and place the CORS enabled URL in the Swagger Explore line.
Now the Process Cloud API’s are presented with all the details we want