Swagger REST API Documention for JSDO Generic Service

Introduction

Swagger is an API Tooling Framework based on the OpenAPI Specification (OAS), and can be used to provide a standard (language-agnostic) interface to REST API’s. Thus, providing the capability to understand and realize the capabilities of exposed Service API’s, without the need to understand or have access to the relevant code base.

Therefore, the Swagger Definition Generator produces REST API Swagger Documentation for SmartComponent Library Business Entities, allowing the consumer to understand and interact with the remote service through the Generic Service Interface for the JSDO or Pacific WebSpeed WebHandler based JSDO Generic Service.

The Swagger Documentation Generator is accessible dynamically through aWeb Handler and can produce static Swagger definitions through a plugin for the Business Entity Designer.

For further information, please check the following links:

https://swagger.io/getting-started/

https://swagger.io/swagger-editor/

https://swagger.io/swagger-codegen/

https://swagger.io/swagger-ui/

The Swagger Petstore, is a working example of how the structure is defined and on how the consumer can interact with the service. 

Swagger Template File Configuration

To avoid fixed / hardwired configuration issues, the Swagger Generation relies on a template file to provide necessary header information (author, description, etc.). The template file is named as “Swaggerfile.json” and should be located within the directory “Consultingwerk/Templates/BusinessEntityDesigner/Swagger”.

Below is the default file configuration:

{ 
  "openapi": "3.0.0", 
  "info": { 
    "version": "1.0.0", 
    "title": "Swagger Consultingwerk", 
    "description": "Consultingwerk Prototype", 
    "termsOfService": "http:\/\/consultingwerk\/terms\/", 
    "contact": { 
      "name": "Consultingwerk",
      "email": "info@consultingwerk.de" 
    }, 
    "license": { 
      "name": "Copyright (C) 2006-2017 by Consultingwerk Ltd.", 
      "url": "http:\/\/www.consultingwerk.de\/legal\/" 
    }
  }, 
  "schemes": [ 
    "http" 
  ]
}

As the Swagger Web Service cannot rely on the Business Entity Designer configuration for the template path (a Unix AppServer will not have access to the Business Entity Designer code base), we have introduced a new setting in the .restapplicaitonsetting files to point to the template folder to allow for customizations:

"templateFolder": "Consultingwerk/Templates/BusinessEntityDesigner"

Registering the Swagger REST API Services within the '.restapplicationsettings' configuration file

 Within the 'restapplicationsettings' file, ensure that you have the following entries defined.

"RestServiceName": "web"
"RestServiceAddress": "\/web\/Resource"
"templateFolder": "Consultingwerk/Templates/BusinessEntityDesigner"


Registering the Web Handler within the PASOE configuration

 

Within the “openedge.properties” file, ensure you have an appropriate entry for the SwaggerWebHandler. 

handler27=Consultingwerk.OERA.Swagger.SwaggerWebHandler: /Swagger/{EntityName}

Note, that OpenEdge does not seem to support gaps in the numbering of Web Handlers. The handler27= ... is only supposed to serve as an example.


The link to the Swagger documentation for Business Entities can be found from the List of Business Services Web Page (e.g. http://localhost:8820/web/BusinessServices/html/Consultingwerk.SmartComponentsDemo.*).


Hosting swagger

The swagger.zip file contains a sampel Swagger website that can be hosted on your PASOE instances, e.g. by unzipping the file into the webapps/ROOT/static/swagger folder.

Business Entity Designer Configuration for Swagger

Configure the Business Entity Designer to load the “SwaggerGenerator” plugin: Consultingwerk.BusinessEntityDesigner.Plugins.SwaggerGeneratorPlugin

Generating Swagger documentation from within the Business Entity Designer

From within the Business Entity Designer, open an existing Business Entity and then choose the “Generate Swagger Schema” option from the Ribbon. You shall be presented with the following:

Select the “Generate” option to produce a Swagger Definitions File.

Related Documentation