Overview
OpenAPI 3.0 is the latest name given to the previous Swagger standard, the market however is still widely familiar with and using the term ‘Swagger’ to refer to OpenAPI 3.0 – as such GLU refers to the GLU.Ware OpenAPI 3.0 as ‘Swagger’. Swagger Specification and API document are used interchangeably. Details on the OpenAPI 3.0 Standard are available here.
GLU.Ware has the ability to generate a Swagger standard based API document to describe the APIs in the GLU.Engine. The API document is compiled in the build process. GLU uses the API configuration (as defined in the GLU.Console) to define the method, schema and structure of the API, and it pulls in the associated API descriptions configured by the analyst in the Integration Builder. The API document is included in the GLU.Engine build such that when the JVM is run a web service will also run to host the Swagger web page to render the API document.
The GLU.Engine Swagger File can be accessed through {Engine_URL}:{Server Port}/swagger. For example: http://mybankapi:9195/swagger
This will display the Open API 3.0 (Swagger) definition for the GLU.Engine APIs.
Download JSON for Swagger Specification
Included in the Swagger specification is a URL which can be used to download the full JSON for the swagger specification.
This JSON can be used to render the swagger definition in the GLU.Control API Manager and/or other swagger management tools.
Console API Control panel
The output of the API document generated by GLU will resemble the following sample.
The GLU.Console API Control Panel is used to configure the API document that will be generated.
The subsequent sections pertain to each of the labeled fields showcased in the API Control Panel screenshot provided above.
A – Swagger API Title
This is the title for the Swagger specification.
B – Swagger API description
This is the description of the API which should provide a description for all the API’s displayed on the Swagger specification and accessed in the GLU.Engine.
The format of this description is HTML.
See below for an example of the API description:
C – Swagger Contact email
This pertains to the contact details for the person responsible to support the exposed API, specifically the email address. Upon selecting this option on the screen, the associated email application will be triggered, and a new email will be created addressed to the provided email address.
D – Swagger API Terms of service URL
The URL to the terms of service for the API.
i.e. www.myorg.legalblurb.com
E – Swagger API Licence URL
The license information for the exposed API.
i.e. www.myorg.termsandSLA.com
F – Swagger Groups
On the Swagger specification it is possible to group API transactions into sections. To do this use the ‘Manage Swagger Groups’ tool.
In the screenshot below you can see how APIs are grouped based on their Swagger Group associations.
G – Manage Swagger Servers
It is possible to configure URL settings to point at the GLU.Engine which contains the API transactions defined in the Swagger specification, this provides the ability to use the web service hosted swagger specification to test each API transaction.
Request Parameters
If samples have not been included in the API transactions configuration, then GLU will generate a schema for the API Request and Response parameters based on the configuration API “body” Request and Response parameters.
The schema is based on Parameter Types.
The table below shows how the parameters are mapped to the Swagger specification.
| GLU.Console Parameter Type | GLU.Console Parameter definition | Swagger definition | Generated in swagger |
|---|---|---|---|
| Text | minLength | string | Yes |
| Text | maxLength | string | Yes |
| Date | includes extra date format definition | string | Yes |
| Text | regex | string | Yes |
| Text | DEFAULT | string | No – default value isn’t included |
| Hash | string | Yes | |
| Integer | integer | Yes | |
| Image | image | Yes | |
| Float | float | Yes |
See below example from the Swagger specification with the mapping.
Show in Swagger Doc: For each transaction there is a tick box which can be used to indicate if a section in the swagger specification should be generated. Tick the box to include in swagger specification, un-tick the box to leave out from swagger specification.
Sample messages for the Request payload as well as Success and Failure Samples for the Response payload can be defined. These where provided will be included into the API Document. When the samples sections are filled in, then these will override the definition of the schema from the request parameters. Instead the value defined in the sample field will be pushed to the swagger specification.
