Skip to main content

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:

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
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

Comments

  1. First and foremost, as Swagger uses a common language that everyone can understand, it’s easily comprehensible for both developers and non-developers. Thus, software developers, product and project managers, business analysts and even potential customers can access API design.

    ReplyDelete
  2. HI Sandeep,
    Thanks for detailed writeup. It is really helpful. I couldn't find the WADLToSwaggerGenerator jar file in the attachments. Could you please provide that jar file as well.

    Thanks
    Mohan

    ReplyDelete
  3. I wish to show thanks to you just for bailing me out of this particular trouble. As a result of checking through the net and meeting techniques that were not productive, Same as your blog I found another one Oracle OSB 12c.Actually I was looking for the same information on internet for Oracle OSB 12c and came across your blog. I am impressed by the information that you have on this blog. Thanks once more for all the details.

    ReplyDelete
  4. Information shared above is highly appreciated. I found the blog very informative. Your article has inspired many of us to learn this. You have shared your deep knowledge on Swagger. Recently i came to know MaxMunus offers the best Swagger training across the globe. If you come across anyone looking for training, you can ask him to contact them directly. They are reachable at:-
    Swagger Training

    ReplyDelete
  5. Swagger API Testing solves business needs while assuring great developer experience by its definition-focused approach.

    ReplyDelete
  6. your valuable information and time. Please keep updating.
    SOA Training
    Oracle SOA Training

    ReplyDelete

Post a Comment

Popular posts from this blog

Dynamic Routing in OSB 12C

Dynamic Routing in OSB cab be used when the BusinessService endpoint required to be determine at runtime in message flow. Consider a scenario where OSB has to route the incoming requests to 2 different services based on the CustomerType element value sent in the payload. So create a XQuery resource with the following contents. Observe that we are using the absolute path of business service in configuration as required by dynamic routing. Following is the XML schema that we use:>>  Customer.xsd <?xml version="1.0" encoding="windows-1252" ?> <xsd:schema targetNamespace="http://xmlns.oracle.com/schema/Customer" xmlns:xsd="http://www.w3.org/2001/XMLSchema"             xmlns:ns1="http://xmlns.oracle.com/schema/Customer">   <xsd:complexType name="Customer">     <xsd:sequence>       <xsd:element name="CustomerId" type="xsd:string"/>       <xsd:elemen

Oracle SOA 12C rest adapter with Custom HTTP headers

Most existing web applications are connected through web services, which are commonly known as SOAP services. More and more users are relying on mobile devices for communication, and they’re looking for lighter ways to access enterprise information on the go. REST services are the answer for the mobile device platform, because they get rapid responses and fast access to data. Oracle SOA Suite 12 c  provides a complete set of service infrastructure components for designing, deploying, and managing composite applications. Oracle SOA Suite 12 c  enables services to be created, managed, and orchestrated into composite applications and business processes. Some time we have need to send HTTP headers in REST service, In OSB we use header component and add what ever is needed but in oracle SOA 12C it's little bit different. Let see how we can do it. Create one SOA Application. Create one SOA Sample project inside SOA Application. Go to composite and drag drop REST adapt