Swagger API document from Any WADL & Schema in Oracle SOA

Hi everyone,

Hope everyone is doing well these days, Recently i started a project work over how to generate swagger API document for your any REST API, In case if you don't know what is swagger please go and check "https://swagger.io/tools/swagger-editor/". It's a great and easy to use tool which will help to create user friendly, human readable form API documentation with extension for generating API client in different languages with capability of testing your API from same.

What is swagger editor,

Design, describe, and document your API on the first open source editor fully dedicated to OpenAPI-based APIs. The Swagger Editor is great for quickly getting started with the OpenAPI (formerly known as the Swagger Specification) specification, with support for Swagger 2.0 and OpenAPI 3.0. 

What benefits you will get by using swagger,

• Runs Anywhere, The Editor works in any development environment, be it locally or in the web.
• Smart Feedback, Validate your syntax for OAS-compliance as you write it with concise feedback and error handling.
• Instant Visualization, Render your API specification visually and interact with your API while still defining it.
• Intelligent Auto-completion, Write syntax faster with a smart and intelligent auto-completion.
• Fully Customizable, Easy to configure and customize anything, from line-spacing to themes.
• All About Your Build, Generate server stubs and client libraries for your API in every popular language.

So after 1 month R&D with hard work finally i completed SOA REST API followed with JAVA & Node JS command line to generate swagger YAML document from any new/existing REST API.

SOA Service Architecture:

Install & Configure node JS (Command Line):

• https://nodejs.org/en/download/
• Download Node JS as per your system env i.e windows/unix/max etc
• Once Node JS installed, Set PATH Env variable.
• PATH: C:\Program Files\nodejs

• Once classpath is set, check by running command “NPM –Version” on command line.

• Run following command on command line to set in case you face any issue while installing Node JS packages used for this.

Use Case	Command	Mandatory status
Set NPM registry	npm config set registry https://registry.npmjs.org	Yes
In case non-SSL connection with NPM registery is needed due to internal n/w access issue	npm config set strict-ssl false	No
In case your n/w firewall not allow to connect with NPM URL, use your internal proxy server	npm config set proxy http://HOST:PORT	No
In case your n/w firewall not allow to connect with NPM URL, use your internal proxy server	npm config set https-proxy http://HOST:PORT	No
In case host name issue, Add below entry in “/etc/hosts file”	151.101.32.162 registry.npmjs.org	No

API Spec Converter installation:

• Download “api-spec-converter-master” from below URL and unzip in some folder location like “C:\Users\L137171\Downloads”
• https://github.com/LucyBot-Inc/api-spec-converter
• On command line go to unzip location of “api-spec-converter-master” like in my case “C:\Users\L137171\Downloads\api-spec-converter-master”
• Open command line and go to this folder location
• cd C:\Users\L137171\Downloads\api-spec-converter-master
• npm install -g api-spec-converter-master
• It will take around 3-5 minutes if you already fixed all issues in above table, In case face any issue verify all details from above table.
• Once installation is completed, Verify installation by below command.
• api-spec-converter –h

How to deploy:

• Login into SOA EM console.
• Go to SOA
• Click on SOA-Infra
• Click Deploy

How to Test:

Sample WADL & XSD Files are available here

Best case usages of swagger:

Open “https://editor.swagger.io/” in browser. Copy generated file content in editor window. Format the copied content by, clicking on Edit >> Convert to YAML. In case you want to convert generated YAML file data to OPEN API, Click on EDIT >> Convert to OpenAPI3. In case you want to generate API client, Follow client option from Main Menu.

Test Deployed Service on SOA EM Console:

• Click on Test button, Following end point will be generated (You can process this WADL file itself after downloading from browser).
• http://localhost:7003/soa-infra/resources/default/WADLToSwaggerGenerator!1.0/SwaggerDocGeneration/application.wadl
• In our case to make testing, we will be testing two WADL, One is this end point by downloading WADL and second WADL with XSD file as this WADL does not have any XSD associated to it.

Test 1 : SwaggerDocGeneration.wadl HTTP Header: Content-Length=10 Input Parameter Name Input Parameter Value XSDFilePath OutputFileName SwaggerDocGeneration WADLFileLocation D:\Swagger\Sample_Testing_File\SwaggerDocGeneration.wadl Response:  Generated Output file in “D” Drive as per deployment configuration in JCA file: Open “https://editor.swagger.io/” in browser. Copy generated file content in editor window. You may see error when you paste file data in editor window like, Go to Line # 36. Now it’s a small manual work where you have to identify response object from generated definition and either map(in case API have response or delete tag in case API don’t have any response), In this WADL we don’t have any response so we will delete these two lines from response. When you delete these two lines make sure generated file indentation not be destroyed as this complete document is a trick of indentation. Once this issue has been fixed, Below is generated UI on editor, Now we will do our second test from this editor only.

Test 2: In the swagger editor click on URI and HTTP method which you need to test in case we are testing POST operation with “/” URI. Click on POST, You will see all generated input parameters with these type of request like it’s a query param/template param/body etc… Enter all data, Now we are testing with a WADL and associated XSD of that WADL. Input Parameter Name Input Parameter Value XSDFilePath D:\Swagger\Sample_Testing_File\GetCoverSummaryProcess.xsd OutputFileName GetCoverSummaryREST WADLFileLocation D:\Swagger\Sample_Testing_File\GetCoverSummaryREST.wadl Click on Execute When you click on “Execute”, It will failed to generate document and you see error in logs like <Apr 30, 2020 9:49:24,448 AM IST> <Error> <oracle.integration.platform.blocks.filter> <BEA-000000> <Content type not found : http://localhost:7003/soa-infra/resources/default/WADLToSwaggerGenerator%211.0/SwaggerDocGeneration/> The issue with highlighted one, Our correct end point is http://localhost:7003/soa-infra/resources/default/WADLToSwaggerGenerator!1.0/SwaggerDocGeneration So swagger doc generator is changing “!” to “%21”, So just replace it with original value and re-test it. Document is available in mapped location. Open the file, Copy and paste file content in editor. Now we have to do again some 0.5% manual work that we did in test 1. Let’s look for every error one by one. Line # 32: For this URI, we don’t have any response XSD element so just delete line #31/32. Go down to next error at old line #47(New line #46) & #52(New line #51), Once you fix any error and make changes in any line, Error line numbers may change. So these two errors are due to default request & response tag mapping, Just map the correct name in ref and error will fly.Now question raised how we get list of definition element from XSD, Go down in same generated document and search for “definitions”. We have these two elements, You have as many as elements based on your XSD, Yellow sign in front of them is a symbol they are not used anywhere. In our case, “process” is a req element and “processResponse” is a response element so just replace them with their default values. All error gone, Click on POST operation, You will see how req/res variable are mapped here, In case you want to check more in depth for these generated elements, click on any of them like click on “process”. When you want to test, it have sample payload for you like, You can check content type in XSL/JSON or you can add any new content type in case missing. For request add in “produce” for response add in “consume”. You can test generated API in same way we did for this test case.

Add on things that you can do manually for advance documentation & API testing

How to add any HTTP or custom header in request: Go to end point URI and HTTP operation which you want to call, Like in my case i need to send a Content-Length header in Post operation for end point URI “/”. Below is my current API document schema. Inside the parameters tag you can see “in” tag with name “body”, so similarly we will add a “in” tag with name “header” in same indexing.         - in: header           name: Content-Length           required: true           type: integer Here name is the header name and type is the value type, it can be string/boolean/integer.    Now check the latest API document for testing as below. How to add request query parameter in request: Go to end point URI and HTTP operation which you want to call, Like in my case i need to send a Content-Length header in Post operation for end point URI “/content/objects/{contentId}”. Below is my current API document schema. As you can inside “parameters” tag we have two “in” tags one is for “header” and one is for “path”, we don’t have any request query parameters here. In the same structure of “in” tag, place below line of code to add query parameter. - in: query         name: queryPrameter         required: true         type: string Below is updated API document.

Hope you enjoyed this implementation.

In case, You are looking for this implementation please connect with me.

Supported implementation:

• JAVA
• SOA-BPEL
• OSB
• J2EE
• JAX-WS
• JAX-RS