Blueriq makes it possible to generate an OpenAPI feed based on your Blueriq REST Services and Exposed Function Flows. OpenAPI, formerly known as Swagger, comes with multiple specifications for defining RESTful interfaces. Blueriq chooses to generate a feed for both OAS 3.0 and OAS(Swagger) 2.0. For all the documentation URLs which are specified here, it is possible to switch between versions via the URL query parameters spec. By default all the documentation URLs will generate a feed according to OAS 3.0. When passing the query parameter spec with the value 2 a feed for OAS 2.0 will be generated.

OpenAPI Specification (OAS) 3.0 vs OAS 2.0 (formerly known as Swagger)

With introduction of the OAS 3.0 a lot has changes for our generated feed. Blueriq no longer generates a feed with anonymous schemas for REST services, it now creates a reference to the schema in the components section of the generated feed. This means that your generated feed will be a lot cleaner then in the OAS 2.0 generated feed. With the OAS 3.0 we have decided to split these the feeds for projects and shortcuts into two separate feeds with different endpoints in order to generate them. The shortcut endpoint only contains paths for the requested shortcut and the project endpoint only contains paths for the requested project. This behavior is unchanged in the OAS 2.0 generated feeds where both projects and shortcuts are concatenated into one single feed.

{
  ...
  "paths": {
    "/rest/Calculator/Calculate/CalculateREST/AddDouble": {
      "post": {
        "summary": "Add",
        "description": "Add two numbers",
        "operationId": "Add",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DoubleAdd-Input"
              }
            }
          }
        },
        ...
        }
      },
      "/rest/Calculator/Calculate/CalculateREST/AddTriple": {
        "post": {
          "summary": "Add",
          "description": "Add two numbers",
          "operationId": "Add",
          "requestBody": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TripleAdd-Input"
                }
              }
            }
          },
          ...
          }
        }
    }
  },
  "components": {
    "schemas": {
      "DoubleAdd-Input": {
        "type": "object",
        "properties": {
          "First": {
            "type": "integer",
            "format": "int32"
          },
          "Second": {
            "type": "integer",
            "format": "int32"
          },
        }
      },
      "TripleAdd-Input": {
        "type": "object",
        "properties": {
          "First": {
            "type": "integer",
            "format": "int32"
          },
          "Second": {
            "type": "integer",
            "format": "int32"
          },
          "Third": {
            "type": "integer",
            "format": "int32"
          },
        }
      }
    }
  }
}

REST Services

The interfaces for REST services can be found at the following locations:

{runtime-url}/server/rest/docs?project={project}&version={version}

Both project and version parameters are required.

{runtime-url}/server/rest/docs?shortcut={shorcut}

The shortcut parameter is required.

Example:

This feed contains information of all operations as defined in REST services that are exposed as webservice by the requested project or shortcut.

Documentation

In the REST service editor, each operation has a field for documentation that will be used in the Swagger feed as the description of the corresponding Operation. The properties of the request/response body schema may be documented in the corresponding Domain Schema per attribute and relation.

Function Flows

The OpenApi feeds for Function Flows that are exposed as webservice are located at:

{runtime-url}/server/api/v2/function/docs?project={project}&version={version}

Both project and version parameters are required. 

{runtime-url}/server/api/v2/function/docs?shortcut={shortcut}

The shortcut parameter is required.

Each Function Flow that is exposed as webservice by the requested project is considered as Operation in the OpenApi interface.

OAS 3.0

If the property `blueriq.production.shortcutsOnly` is set and the Runtime is running in production mode, the project feed will throw a forbidden exception.

OAS 2.0

If the property `blueriq.production.shortcutsOnly` is set and the Runtime is running in production mode, the project feed will only contain shortcuts.

Documentation

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.

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.