Generating an OpenAPI representation

OpenAPI is a standardized version of the Swagger specification. It provides a language-independent way to present REST APIs. You can generate OpenAPI representations for executing decision services. This capability is part of ODM Decision Connect, which enables reusable decisions to be exposed as OpenAPI based public APIs to be invoked directly by applications. The OpenAPI-based decisions can also be published to an IBM API Connect catalog for managed APIs. IBM API Connect Essentials is also an optional part of Decision Connect.

About this task

To write JSON input for the POST method to a specific ruleset endpoint URI, you can generate the OpenAPI representation. The OpenAPI representation contains one entry for the POST method.

To generate an OpenAPI representation, you can use the Endpoint URIs. For more information about OpenAPI, see The OpenAPI Specification page of the Open API Initiative website.

Note: The REST APIs use OpenAPI 3.0. For more information, see OpenAPI Specification.

Procedure

Define the request:
```
https://<vhostname>.bpm.ibmcloud.com/odm/<odm_on_cloud_environment>/DecisionService/rest/v1/{rulesetPath}/openapi?format={format}
```
Set {format} to the format of the OpenAPI definition file, which is either YAML or JSON. The default format is YAML.

The URI variables are defined in Endpoint URIs.
The following example shows a request to generate an OpenAPI representation in YAML format:
```
GET https://vhost005.bpm.ibmcloud.com/odm/dev/DecisionService/rest/v1/miniloanruleapp/1.0/miniloanrules/1.0/openapi?format=YAML
```
Optional: To use the OpenAPI file in IBM API Connect®, use the extension query parameter and specify apiconnect.
The following example shows a request to generate an OpenAPI representation in YAML format and use it in IBM API Connect:
```
GET https://vhost005.bpm.ibmcloud.com/odm/dev/DecisionService/rest/v1/miniloanruleapp/1.0/miniloanrules/1.0/openapi?format=YAML&extension=apiconnect
```

Results

You generated an OpenAPI representation in YAML or JSON format.

If you used an invalid URL or if an error occurs during the OpenAPI generation, an error status code is returned.

If you sent the request from a browser, an HTML page displays the error message.
Note: The status code is 200 despite the error message because it applies to the HTML page, not to the request result.
If you sent the request from a client other than a browser, a status code 404 (Not Found) is returned and the error is described in XML.

You can find a description of error messages in HTTP status codes.