Page History
| Info | ||||
|---|---|---|---|---|
| ||||
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 icon
is used to indicate where a description can be added.
OpenAPI Specification 3.1.0 | Corresponds with … in Blueriq | Location (editor) in Encore |
|---|---|---|
Version number in the URL of the feed. See also: OpenAPI | - | |
OpenAPI title in project in Encore. If empty: "Rest Services”. | ||
OpenAPI description in project in Encore. If empty: “A specification of the exposed rest services available in the Blueriq Runtime”. | ||
URL of the runtime server from which the feed is generated. | - | |
Name of the rest service element in which the operation is defined in Encore. | ||
/[Name of Web service element in Encore]/[Name of fragment in REST service in Encore] | ||
Selected HTTP method of the operation in REST service in Encore. | ||
Name of operation in REST service in Encore. | ||
OpenAPI description of operation in rest service in Encore. | ||
Name of webservice + Name of operation in REST service in Encore | ||
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. | ||
Request domain schema in operation in REST service in Encore. | ||
Response domain schema in operation in REST service in Encore. | ||
Default runtime responses named RestErrorResponse, InvalidJsonPathDetail, and InvalidJsonResponse that are used for default error responses (400, 401, 403, 404, 406, 500) | - | |
[ModuleName]_[DomainschemaName] | ||
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. |
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.
| Tip |
|---|
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. |
Overview
Content Tools