See the supported connectors for Application Integration.

View OpenAPI Specification for your integration

Preview — OpenAPI Specification

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

Application Integration provides the ability to dynamically generate and view the OpenAPI Specifications of your published integrations that are configured with one or more API triggers. Accessing the OpenAPI Specification of your integration allows you to:

• Gain a comprehensive understanding of your integration's API endpoints, methods, and data structures.
• Enable more efficient development and troubleshooting by providing a detailed and centralized view of your integration's API.
• Expose your integration APIs and seamlessly integrate with conversational agents, see Build conversational agents with Application Integration.

What is the OpenAPI Specification?

The OpenAPI Specification (OAS) is a standard, language-independent format to describe RESTful APIs. Commonly written in either YAML or JSON formats, the OpenAPI Specification presents a formal description of the API elements such as its base URL, paths and verbs, headers, query parameters, content types, request and response models, and more. For more information about the OpenAPI Specification, see OpenAPI Specification.

Note: Application Integration only supports OpenAPI Specification version 3.0.1.

Generate and view the OpenAPI Specification

You can dynamically generate and view the OpenAPI Specification for your integrations from the Integration editor in the Google Cloud console or using an API call.

Before you begin

• Confirm that your integration is configured with one or more API triggers. For information about configuring API triggers, see API triggers.
• Publish your integration. For information about how to publish an integration, see Test and publish integrations.

View OpenAPI Specification

To view the OpenAPI Specification for your integration, select one of the options:

Console

To view the OpenAPI Specification for a specific integration, do the following steps:

1. Go to the Application Integration page.

   Go to Application Integration

2. In the navigation menu, click Integrations.

   The Integrations page appears, listing all the integrations available in the Google Cloud project.

3. Click the integration for which you want to view the OpenAPI Specification. This opens the integration in the Integration editor.
4. Click the (Actions menu) in the Integration editor toolbar, and select View OpenAPI spec.

   The View OpenAPI spec pane appears displaying the OpenAPI Specification of the integration. The generated OpenAPI Specification, by default, contains all the API triggers configured in the integration.

   • To view the OpenAPI Specification for a specific API trigger, select the API trigger from the APIs drop-down list.
   • To download the OpenAPI Specification as a YAML file, click download (Download).

Note: You can only view and download the OpenAPI Specification, in YAML format, for a single integration from the Integration editor at a time. To view and download the OpenAPI Specification, in YAML or JSON formats, follow the instructions in the API section.

API

The generateOpenApiSpec method of the Application Integration API allows you to view the OpenAPI Specification for your integration using an API call.

Use the following curl command to view the OpenAPI Specification for one or more integrations in the same region:

Tip: curl typically comes pre-installed for Linux and macOS operating systems. If you don't have curl, you can download it from the curl releases and downloads page.

curl -X POST \
    -H "authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{
    "apiTriggerResources": [{
    "integrationResource": "INTEGRATION_NAME",
    "triggerId": ["api_trigger/TRIGGER_NAME", "api_trigger/TRIGGER_NAME_2", "api_trigger/TRIGGER_NAME_n"]
    },
    {
    "integrationResource": "INTEGRATION_NAME",
      "triggerId": ["api_trigger/TRIGGER_NAME"]
    }],
    "fileFormat": "DOC_TYPE"
    }' \
    "https://LOCATION-integrations.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION:generateOpenApiSpec"
          

Replace the following:

• TRIGGER_NAME, TRIGGER_NAME_2, TRIGGER_NAME_n: The names of the API trigger in your integration which you want to view the OpenAPI Specification for.
• INTEGRATION_NAME: The name of your integration.
• DOC_TYPE: The type of document to generate. The following values are supported: YAML or JSON.
• PROJECT_ID: The ID of your Google Cloud project.
• LOCATION: The location of your Google Cloud project.
  Note: You can only view the OpenAPI Specification for multiple integrations in the same region.

Understanding the OpenAPI Specification

Application Integration generates the OpenAPI Specification for your published integrations following the OpenAPI Specification 3.0 standard. The following table describes the elements of the OpenAPI Specification generated in Application Integration:

Element	Description
openapi	The OpenAPI Specification version used.
info	Information about the integration, such as its name (title), description, and published version.
servers	The server URLs that host the integration.
paths	Paths are created for each selected API trigger in the integration. The server URL combined with the path constitutes the API endpoint for making API calls. Request and Response fields are populated based on the input and output variables configured for the corresponding API trigger. Note: Application Integration currently supports only a limited set of JSON schema keywords. For information on the supported keywords, see Considerations.
components	The schemas field contains the JSON schema for the input and output variables of the API trigger. The securitySchemes field contains the authentication information for the API triggers.

Considerations

The following considerations apply when viewing the OpenAPI Specification for your integration:

• The OpenAPI Specification is generated only for published integrations.
• The OpenAPI Specification is generated only for integrations configured with one or more API triggers.
• The OpenAPI Specification is generated only for integrations in the same region.
• The OpenAPI Specification is generated in YAML format by default. To generate and view the OpenAPI Specification in JSON format, set the fileFormat parameter to JSON in the API call.
• Application Integration currently supports only the following limited set of JSON schema keywords:
  • type
  • items
  • properties
  • description
  • required
  • array
  • object
  • oneOf
  • allOf
  • anyOf
  • not
  • null
  • enum
  • additionalProperties
  • default
• When validating the OpenAPI specification using the Swagger Editor, you may encounter semantic errors related to the API paths similar to the following image:

  

  These errors can be safely ignored. The OpenAPI Specification is still valid.

What's next

• Build conversational agents with Application Integration.
• Learn about API triggers.
• Learn about Test and publish integrations.