Importing an OpenAPI file

How to import an OpenAPI file

1. Select a repository and branch in the navigation panel and open the context menu () of the selected branch.
2. Select "Import OpenAPI definition".
3. Now, an OpenAPI file needs to be provided. You can choose between two sources that need to be a valid OpenAPI 3.0 or 3.1 file in JSON or YAML format: 
   1. Upload from a local file: You can select a file from your local storage. 
   2. Import from a URL: Alternatively, you can provide a direct URL link to the OpenAPI file for import and select "Fetch from URL". You can for example use the OpenAPI feed of a Blueriq webservice. Read here how to get its URL.  
4. Select the project and module in which you want to import the definition.
5. Proceed to the next step to select which operations you wish to import.

   Certain features described in a valid OpenAPI file may not be supported by Blueriq. During the import process, unsupported features are identified for each operation and are ignored where applicable, allowing to import most aspects even in the presence of unsupported aspects.

6. After selecting "Import", all generated elements will be saved and the newly created REST service elements will be opened automatically

Model generation and support

The OpenAPI import in Blueriq Encore generates a model based on an OpenAPI 3.0 or 3.1 file in JSON or YAML format. 

Some things to consider about the model generation are:

• Element types that may be created during this import include: Interaction module, Entity, Relation, Attribute, Value list, REST service, Domain schema.
• For each path object in the OpenAPI file, a REST service operation will be generated.
  • REST operations are grouped into REST services by their first available tag. Path objects without any tags are grouped into a single REST service that is named after the title of the OpenAPI definition.
• For each schema in the OpenAPI file that is used in a selected operation, a domain schema will be generated.
• If an element already exists in the selected module, it will be overwritten.
• Supported HTTP methods are: GET, POST, PUT, DELETE, PATCH.
• The supported media type is application/json, or derived JSON types (e.g. application/hal+json) are also supported.
  • If no JSON media type is present, then the wildcard media type */* is used if it is specified.
• Security schemes are not supported and are silently ignored.
• Blueriq can only handle one response schema. This will be the schema that corresponds with the status code 200, or lowest response in the 200-399 range if 200 does not exist, or "default" otherwise.
• OpenAPI examples and descriptions are ignored during the import.
• Only single files can be imported; external references are not supported.

Consuming vs. creating a webservice

The OpenAPI import in Blueriq Encore is designed for consumption of a webservice. You may however choose to expose the imported operations as a webservice operated by Blueriq by creating a webservice in a configuration module and changing the direction of the REST service from 'Outgoing' to 'Incoming' or 'Both'.