To enable generation and display of REST API in CEE, two new interfaces have been introduced:

• Swagger Service

• Swagger UI

Introduced Interfaces

Swagger Service

A web service with an endpoint for generating swagger.json file, available at the path: “/services/rest/com.cisag.sys.tools.swagger.rest.SwaggerService/swagger”

• This endpoint returns documentation for all available REST API endpoints in the format specified by the OpenAPI specification.

Swagger UI

A web application located at the path:

/swagger

• The application fetches JSON documentation from the Swagger Service and displays it in graphical form.

Displayed endpoints

All endpoints that are present in applications from the category Web Service with the special usage defined as REST Service will be included in the generated documentation.

Structure

The Servers section contains a list of server addreses to be used as prefixes for sending request via the Swagger API.

• In the current version, each server URL contain inbuilt database.
• This is the OLTP database that will be used for handling sent requests.

API Endpoints

The REST endpoints are grouped by their respective service. Each endpoint contains:

• relative request path
• request parameters
• request body
• possible responses

Request path

The request path represents the relative path of a endpoint. It is a concatenation of the service path and the endpoint path.

•  /services/rest/com.cisag.sys.tools.swagger.rest.SwaggerService/swagger

Request parameters

If the endpoint takes any parameters, they will be displayed in the Parameters section.

For each parameter, the following information is provided:

• name,
• type,
• source (path, query, header, cookie),
• information on whether it is required.

Parameters do not require any additional annotation. The Swagger implementation uses annotations already used for param definition in web services.

Request body

This section represents the structure and format of request body passed into endpoint.

• Request body does not require any additional annotation.
• Implementation includes additional annotation: com.cisag.sys.tools.swagger.annotations.RequestBody, which can be used to provide additional description for the request body.
• Annotation should be used on the parameter representing the request body.

Responses

This section details possible responses that user can get from the endpoint. Each response must contain:

• response code
• description

Response can also contain a response body example.
However defining will require in code definition, with additional annotations.

Required annotations:

• io.swagger.annotations.ApiResponses — container for all response definitions for a given endpoint
• io.swagger.annotations.ApiResponse — definition for a single API response

Section Responses

@GET
@Path("swagger")
@ApiResponses({
@ApiResponse(code=200, message = *Successful generation of json file*, response = Specification.class),
@ApiResponse(code=403, message = *Not enough privileges*),
@ApiResponse(code=500, message = *Error occurred during loading classes*)
})
@Produces("application/json")
public Response exampleMethod(){
// Method definition
}

Body format

• Assigned from javax.ws.rs.Produces annotation.

• If not specified, the application/json format is assigned.

Schemas

• If at any point generator encounters complex object it is saved as a schema object and then only referenced in any occurences.
• Schema object contains full recursive structure of object.
• Marking of [] (example [string]) in the field type defines field as an array type.

Test mode

Swagger UI provides test mode, for testing available endpoint:

It is acivated by the [Try it out] button, in the endpoint view:

After launching test mode, both body and all parameters become editable.

Clicking the [Execute] button sends the request.

Base URL of request will be determined by the current selection in the Servers section.

All required parameters must be filled before sending the request.

Clicking [Cancel] button exits test mode.

Example test mode

Endpoint without parameters or body:

Endpoint with parameters and body:

Example response:

Required Permissions

To use Swagger UI embedded in Comarch ERP Enterrpise user needs to have access both to:

• com.cisag.sys.tools.swagger.SwaggerUI
• com.cisag.sys.tools.swagger.rest.SwaggerService

Without these permissions, the access to Swagger UI and Swagger Service will be denied.

Additionally, the following Capability must be assigned to the user:

•  com.cisag.sys.tools.swagger.rest.GetRESTSwaggerDocumentation

Without this Capability, a 403 response code will be returned by Swagger Service