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.

Before you begin

Before you can use the REST service in a client, you must start the sample server or configure Rule Execution Server for your application server. See Starting and stopping the sample server or Configuring.

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 External link opens a new window or tab

page of the Open API Initiative website.

Note: The REST APIs use OpenAPI 3.0. For more information, see OpenAPI Specification External link opens a new window or tab

Procedure

Define the request:
```
http://{host}:{port}/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 http://localhost:9080/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 http://localhost:9080/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.

Note: The generated OpenAPI representation do not contain any tag by default. If you need the REST execution method to be associated with a tag, you can use the OpenAPITagNameForExecutionMethod parameter (see HTDS context parameters).

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.