OpenAPI / Swagger Generator

v3.15.0+

Introduction

Using the Generator approach, it's possible to connect to services described by OpenAPI or Swagger, generating much of the needed models or parts of the models to get going.

The following features are currently supported:

Generating a Service Model

One of the key capabilities of this feature is the generation of a Service Registry model. The resulting model can interact with an external service defined by an OpenAPI or Swagger specification, and can be used in a BPMN process model or a CMMN case model to interact with the 3th party service.

Extracting Type Definitions for Data Dictionary

In addition to creating Service models, the wizard also facilitates the extraction of type definitions from your OpenAPI or Swagger specifications. These extracted types are then incorporated into a Data Dictionary model within the app.

This Data Dictionary model then serves as a central repository for data structures and types, ensuring consistency and ease of use across different models and processes.

Using the Generator Wizard

Starting the wizard: The model generation feature includes a user interface that guides you through the entire process. This approach ensures that you can easily navigate through the steps required to generate a model with the ability to review the generated models before importing them into your app.

You can access it through the Create button inside an app in Flowable Design. Select OpenAPI / Swagger from the listing of generators:

A wizard will launch to guide you through the following steps:

1. Import an OpenAPI or Swagger spec.
2. Configure the generator.
3. Review the generated models.
   • Import the generated models into your app or go back to a prior step to adjust generator settings.

Generator Settings Reference

In the generator settings step you can choose which models to generate. The following sections describes the available models to generate and their settings.

Service

The Service model outlines the operations specified in your OpenAPI spec, including input and output parameters.

The OpenAPI Generator facilitates the following Generator settings:

Name	type	Description
Generate	checkbox	Whether to generate the service model or not.
Service model key	input text	You can define your custom model key here. If left blank, the generator will use a default key.
Single Input parameter	checkbox	See description below.
Single Output parameter	checkbox	See description below.
Generate example data	checkbox	When checked, the generator produces example data for input out parameters making it easier to understand the structure of the data the service produces or expects

Single parameter setting

This setting configures whether the payload is provided as flat list of input or output parameters or as single json payload. The following example illustrates the difference for the OpenAPI Petstore example for the create Pet operation:

Default setting:

The default setting generates a list of input parameters for value attributes. Nested structured types are defined as json or array types, according to the spec.

Single input setting:

The single input setting generates just a single input parameter. In this case a json structure representing a pet is expected.

Data dictionary

The data dictionary model represents the defined schema types in the specification.

Name	type	Description
Generate	checkbox	Whether to generate the service model or not.
Service model key	input text	You can define your custom model key here. If left blank, the generator will use a default key.

info

Both models are generated independently. For the time being, they exist separately and are not interconnected. You can also just generate either of them.

Limitations

The generation is done on a best-effort basis. It might require manual adjustments for certain cases.

• Composed schemas / inheritance e.g. usage of allOf, anyOf is not yet supported.
• Only JSON schemas are considered. XML schemas are not supported and are ignored.
• Only primitive values for query parameters are supported (e.g. no arrays or objects)
• Cookie parameters are not supported.
• Swagger 2.x and OpenAPI 3.0 are supported. OpenAPI 3.1 is not officially supported.
• Not all schema types (like binary) are supported yet.

note

The tool may not cover all OpenAPI spec complexities, potentially requiring manual adjustments. For best results, simplify your specification to essential operations where possible.