Page tree
Skip to end of metadata
Go to start of metadata

Swagger REST API Documentation for RESTful Services

 

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 realise the capabilities of exposed Service API’s, without the need to understand or have access to the relevant code base.

RESTful services provide an alternative HTTP and JSON based interfaces for third party applications or mobile applications (the JSDO generic service is specialized to be used by JSDO based clients).

Therefore, the Swagger RESTful Services Generator produces REST API Swagger Documentation for SmartComponent Library Business Entities exposed as RESTful services, allowing the consumer to understand and interact with the remote service.

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.

Configuring Business Entities as RESTful Resources & Initializing the REST Address Service

For details, please follow the link below:

http://documentation.consultingwerkcloud.com/display/SCL/RESTful+services

Setting up the PASOE environment

We support exposing Business Entities as RESTful services through a PASOE Web Handler.

Registering the Swagger RESTful Services within the '.restapplicationsettings' configuration file

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

"RestfulEntitiesAddress": "\/web\/Entities"
"templateFolder": "Consultingwerk/Templates/BusinessEntityDesigner"

Registering the Swagger RESTful Services Web Handler within the PASOE environment

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

handler27=Consultingwerk.OERA.RestResource.RestEntitiesWebHandler: /Entities
handler29=Consultingwerk.OERA.Swagger.SwaggerRestEntitiesWebHandler: /SwaggerEntities/{OutputType}

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

The entry registers the SwaggerRestEntitiesWebHandler for the /web/SwaggerEntities URI.

The “{OutputType}” allows only two values.

OutputType

Description

html

Produces the Swagger Html page containing the API Services

json

Produces a flat json schema of the API Services

Swagger Template File Configuration

To avoid fixed / hardwired configuration issues, the Swagger Generation relies on a template file to provide necessary information. 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:

{
  "swagger": "2.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"
  ] 
}

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

Query String Parameters

RESTful requests for collections can be filtered using query string parameters.

Parameter Name

Description

fields

comma delimited list of field names to be returned

sort

The sort criteria as a comma delimited list in the form of +fieldname or -fieldname, e.g. sort=+country,-city

limit

The maximum number of records returned from a collection

offset

The first record to be returned, allows paging in combination with the limit parameter, e.g. limit=20&offset=20

{fieldname}

filter criteria, e.g. salesrep=BBB&creditlimit>=10000 - supported operators are =, >=, <=, >, <>, <

Within the Swagger API, this is achieved on collections with a “?{filter}” attribute.

Samples

Running the following link:

http://localhost:8820/web/SwaggerEntities/html

would produce the following output:

 

 Running a Filter Query

 

 Response:

 

Related Documentation