[Proposal] Support storing OpenAPI definitions of APIs in the API platform

[Piumal1999]

Problem

In the Developer Portal, features such as API Try Out, displaying API resources, scopes, and security schemes require an OpenAPI definition. However, this definition is not currently stored in the platform. As a result, when publishing an API to the Developer Portal through the Management Portal, it is not possible to provide a complete OpenAPI definition with all the necessary details.

Existing Behavior

Currently, the source of truth for an API in the platform is the configuration given as api.yaml artifact. The actual OpenAPI definition is not stored.

Even when an API is created or imported using an OpenAPI definition, that definition is not preserved. Instead, it is converted into api.yaml format, and much of the original information is lost. This is acceptable for the Management Portal and Gateway, as api.yaml contains all the required details for their operation.

When an API is published to the Developer Portal, a new OpenAPI definition is generated from the content in api.yaml. This generated definition lacks details such as securitySchemes, response formats, schemas, examples, and other metadata, limiting the functionality of the Developer Portal.

Proposed Solution

To address this limitation, it is preferable to optionally store the OpenAPI definition within the platform, make it editable, and keep it synchronized with api.yaml. This would allow users to enhance and customize additional details as needed. When publishing an API to the Developer Portal, the stored OpenAPI definition can then be used directly, enabling the portal to function independently of the control plane and gateway.

At the same time, api.yaml should remain the source of truth for the Management Portal.

It is required to ensure that the OpenAPI definition stays in sync with api.yaml.

• For example, in an ideal scenario, when a user adds an API key policy to a resource and with an API key header, the platform should automatically update the OpenAPI definition with the corresponding securityScheme element and header details.

Implementation Steps

• Add support for storing the OpenAPI definition in the database
• Extend REST APIs to allow editing of the OpenAPI definition
• Implement UI functionality for editing the definition
• Implement the synchronization mechanism