Swagger REST API Documentation for RESTful Services
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:
{ "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" ] }
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: