Swagger – OpenAPI 3.0

Overview

Naming Convention Note: 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’ too. Swagger Specification and API document are used interchangeably. Details on the OpenAPI 3.0 Standard are available here: https://swagger.io/specification/

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

As an 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.

swaggerlink


This JSON can be used to insert into the GLU.Control API Manager or other tools.

GLU adheres to the Swagger specification as defined above, this means that for example, if Swagger samples messages are configured in the GLU.Console for the GET method, those samples won’t be generated into the API document as message samples for a GET call do not adhere to the Swagger specification. The specification will override the GLU.Console configuration.

Console API Control panel

The GLU generate API document will look like this the sample below.

exampleSwagger


The GLU.Console API Control Panel is used to configure the API document that will be generated.

gluconsoleS


The sections below refer to each of the labelled fields in the API Control Panel screenshot above.

A – Swagger API Title

This is the title for the Swagger specification.

B – Swagger API description

This is the description of the API describing all the API’s displayed on the Swagger specification and grouped together in the GLU.Engine.

The format of this description is HTML, as such rendering will conform to HTML standards.

An example of an API description:

exdesc


C – Swagger Contact email

The contact information for the exposed API, i.e. email address. When this is selected on the screen, it will force the associated email application to create an email to this email address.

D – Swagger API Terms of service URL

A URL to the Terms of Service for the API. This MUST be in the format of a URL.

E – Swagger API Licence URL

The license information for the exposed API, if any.

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.

group


In the screenshot below you can see how APIs are grouped based on their Swagger Group associations.

group2


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 provided the ability in the Swagger specification to test each API transaction.

server


Request Parameters

Schema

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 TypeGLU.Console Parameter definitionSwagger definitionGenerated in swagger
TextminLengthstringYes
TextmaxLengthstringYes
TextDD/MM/YYYYstringNo
TextregexstringNo
TextDEFAULTstringNo
HashhashNo
IntegerintegerYes
ImageimageYes
FloatfloatYes

Show in swagger specification

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.

showInSwagger


Samples

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.

sample
Was this article helpful?

Related Articles

Leave a Reply

Your email address will not be published. Required fields are marked *

Fill the form and we’ll contact you shortly

    I agree with

    cookies
    We uses cookies to make your experience on this website better. Learn more
    Accept cookies