Swagger REST API Documentation for RESTful Services
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.
For details, please follow the link below:
http://documentation.consultingwerkcloud.com/display/SCL/RESTful+services
We support exposing Business Entities as RESTful services through a PASOE Web Handler.
Within the 'restapplicationsettings' file, ensure that you have the following entry defined.
"RestfulEntitiesAddress": "\/web\/Entities" "templateFolder": "Consultingwerk/Templates/BusinessEntityDesigner" |
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 |
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
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.
Running the following link:
http://localhost:8820/web/SwaggerEntities/html
would produce the following output:
Response:
