You are viewing the documentation for Blueriq 17. Documentation for other versions is available in our documentation directory.

What is it for?

The OpenAPI feed is used to describe and communicate (the interface of) a Blueriq web service with its consumers.

By default, all exposed operations of rest services and exposed functions witin a project are exposed in an OpenAPI feed. 

How to use the OpenAPI feed

The OpenAPI feed is exposed by the runtime in JSON format. Read more about supported versions and how to get the URL here.

For a human readable version during development, you could paste the JSON into tools such as https://editor-next.swagger.io/

You can use the specification to add your Blueriq webservice to an API store so that it can be consumed easily by other parties. Use the OpenAPI import in Encore if you wish to use a Blueriq application to consume a Blueriq webservice.

Blueriq REST Services

Most parts in the Blueriq OpenAPI feed are generated automatically based on the model. Other parts have to be added and maintained by the Business Engineer. The table below shows the relation between the Blueriq model in blueriq Encore and its generated OpenAPI feed. In Blueriq Encore, the OpenAPI iconis used to indicate where a description can be added.  

OpenAPI Specification 3.1.0

Corresponds with … in Blueriq 

Location (editor) in Encore

OpenAPI version (4.1)

Version number in the URL of the feed. See also: OpenAPI

-

Title (4.8.2)

OpenAPI title in project in Encore. If empty: "Rest Services”.

Project

Description (4.8.2)

OpenAPI description in project in Encore. If empty: “A specification of the exposed rest services available in the Blueriq Runtime”.

Project

Server url (4.8.5)

URL of the runtime server from which the feed is generated.

-

Operation tag (group) (4.8.22)

Name of the rest service element in which the operation is defined in Encore.

REST service

Path item object (4.8.9)

/[Name of Web service element in Encore]/[Name of fragment in REST service in Encore]

Web service, REST service

Operation object (4.8.10)

Selected HTTP method of the operation in REST service in Encore.

REST service

Operation summary (4.8.10)

Name of operation in REST service in Encore.

REST service

Operation description (4.8.10)

OpenAPI description of operation in rest service in Encore.

REST service

Operation id (4.8.10)

Name of webservice + Name of operation in REST service in Encore

Web serviceREST service

Operation parameters (4.8.12)

Headers, arguments, and fragments in operation in rest service in Encore, including its properties such as OpenAPI description, whether the parameter is required, values of a value list that is attached to an attribute in case of a dynamic parameter.

REST service, attribute, value list

Request body (4.8.13)

Request domain schema in operation in REST service in Encore.

REST service

Response 200 OK (4.8.17)

Response domain schema in operation in REST service in Encore.

REST service

Other responses (4.8.17)

Default runtime responses named RestErrorResponse, InvalidJsonPathDetail, and InvalidJsonResponse that are used for default error responses (400, 401, 403, 404, 406, 500)

-

Schema (4.8.24)

[ModuleName]_[DomainschemaName]

Module, domain schema

Schema properties  (4.8.24)

Properties of a domain schema item, containing the name, data type, whether its required, whether its multivalued, OpenAPI description, values of a value list that is attached to an attribute that is mapped to a domain schema field.

Domain schema, attribute, value list

Blueriq Function Flows

In the Function tab of a Function Flow, you have the ability to specify documentation for the function in general and for each input and output parameter. Use the OpenAPI icon to do so.

The general function documentation is available in the OpenAPI feed as the description of the operation. The parameter's documentation is specified in the OpenAPI feed in the body schema definition.

Use of CommonMark in OpenAPI descriptions

The OpenAPI specification supports the use of CommonMark (v0.27) markdown throughout descriptions fields allowing for rich text formatting. 

Use a double newline (2x enter) in an OpenAPI description field in Blueriq Encore to add structure to the descriptions. This will start a new paragraph in the feed.