Using OpenAPI builder

IBM watsonx Orchestrate platform gives you the capability to build, edit, or generate OpenAPI specifications (OAS). The OpenAPI builder function uses Artificial Intelligence (AI) to simplify the process of generating these specifications, making it easier for you to create your custom skills.

Generate an OpenAPI specification from documentation web page

You can generate an OAS from a documentation web page by using AI. The documentation web page must contain cURL or HTTP requests and JSON responses. You can't provide the main documentation page as the URL, as the system doesn't process the pages recursively.

To generate an OAS from a documentation web page:

  1. From the menu menu, select Skill studio.

  2. Click Create and choose the Import API option.

  3. Choose OpenAPI builder (experimental).

  4. Click the OpenAPI builder tile.

  5. Select AI generate a new OpenAPI spec.

  6. Specify the required API's documentation URL in the Import URL field. For example, to generate OAS from GitHub REST API, provide the link https://docs.github.com/en/enterprise-server@3.5/rest/orgs/orgs in the field.

  7. Click Generate.

  8. Select the endpoints that you want to include in the specification from the list.

    Endpoints
    Figure 1: Selecting the endpoints.

  9. Click Generate Selected. You can find the selected endpoints in the specification generated.

    Editor view
    Figure 2: OpenAPI in the Editor view.

Now, you can review the OAS generated and start to edit. For more information on editing specifications in the OpenAPI builder, see Using editors in the OpenAPI builder.

Open an existing OpenAPI specification

You can open an existing OAS and edit it within the watsonx Orchestrate platform.

To open an existing OAS:

  1. From the menu menu, select Skill studio.

  2. Click Create and choose the Import API option.

  3. Choose OpenAPI builder (experimental).

  4. Click the OpenAPI builder tile.

  5. Select Open an existing spec.

  6. You can open an existing specification in one of the following methods:

    i. To open a specification from a URL, specify the URL in the Import URL field and then click Download from URL.

    Open spec from URL
    Figure 3: OpenAPI builder page: import a specification from URL.

    ii. To open a specification from your system:

      a. Click Choose file.

      b. Select the required file, and click Open.

      c. Click Open Local to open the specification.

    Open spec from system
    Figure 4: OpenAPI builder page: open a specification from system.

Now, you can view the specification in the OpenAPI builder. You can edit the specification or apply AI suggestions to your specification. For more information, see Using editors in the OpenAPI builder.

Create an OpenAPI specification from scratch

You can create an OAS from scratch by using the watsonx Orchestrate OpenAPI builder.

To create an OAS:

  1. From the menu menu, select Skill studio.

  2. Click Create and choose the Import API option.

  3. Choose OpenAPI builder (experimental).

  4. Click the OpenAPI builder tile.

  5. Click Create an OpenAPI specification from scratch to open the editor.

  6. Add the specifications. For more information on OpenAPI specification requirements, see Creating OpenAPI specifications.

  7. Click Apply changes to save your changes to the file.

  8. Click Download spec to download the OpenAPI file to your system.

    Creating a new spec
    Figure 5: Creating an OpenAPI specification from scratch.

You can import the OpenAPI specification file to watsonx Orchestrate to add the skills.

Using editors in the OpenAPI builder

In the OpenAPI builder, you can use AI to generate a OpenAPI specification from documentation and you can edit the specification in an editor that can enhance it with AI suggestions.

You can view or edit the OAS in the following formats:

  • Visual+AI view

    In the Visual+AI view, you get a visual representation of the API. You also get AI-generated suggestions to create your OAS.

    To edit OAS in Visual+AI format, see:

  • JSON view

    In the JSON view, you get the OAS in the text format.

    To edit OAS in JSON format, see:

  • OpenAPI view

    The OpenAPI view shows the API according to the standardized OAS.

By default, you can see the specifications in JSON view and OpenAPI view. To get the Visual+AI view, set Visual+AI view to on.

Editor view
Figure 6: Specifications in Visual+AI view, JSON view, and OpenAPI view.

Note: You can click the home icon to go to the OpenAPI builder home page.

Download OAS from OpenAPI builder

You can download the specification as a JSON file to your system and import it into watsonx Orchestrate or other tools that work with OAS. You can also import a specification into the OAS builder again to enhance it some more.

To download an OAS file from the OpenAPI builder, click Download spec.

Download file from OpenAPI builder
Figure 7: OpenAPI builder: Download spec button