Manage OpenAPI Schemas

Overview

Whether you got started with the Speakeasy platform by integrating the SDK first and letting Speakeasy capture your traffic or you uploaded an OpenAPI Schema to have Speakeasy start watching for traffic that matches your schema, you can benefits from Speakeasy's Open API Schema Generation.

Schema generation works via our traffic capture functionality, any time the Speakeasy platform sees new traffic from one of your APIs and we detect it is not present in an OpenAPI Schema associated with that API, we can alert you and allow you to generate a schema from the traffic we received, allowing you to update your schema without the need of manually writing it from scratch.

Upload Existing OpenAPI Schema

The API dashboard can be used for tracking incoming traffic against your API's existing OpenAPI 3.0.x Schema. The Speakeasy platform will try to associate any incoming traffic from an API with a Schema that has been uploaded to the API dashboard.

The schema can be uploaded before or after you start tracking traffic with the SDK.

If uploaded before you will upload the Schema using the ApiID and Version you intended to configure in the SDK for any incoming traffic. Once uploaded you will then see the API and API Endpoints present in your schema but no metrics will be visible until the SDK starts sending traffic for the same ApiID and Version.

If uploaded after traffic is already being received from the SDK you will select a pre-existing ApiID and Version to upload a schema for and then the Speakeasy dashboard will associate your Schema with any pre-existing API Endpoints that have already been received.

Associating a Schema with your traffic can help with detecting drift between your deployed code and your OpenAPI schema which may be the source of truth for your documentation. Read more about how Speakeasy can help you keep track of this drift here.

Detecting new API Endpoints

Speakeasy's schema generation works by detecting new traffic that can't be associated with a Path & Path Object in a OpenAPI Schema document associated with one of you APIs.

tip

If you don't have an existing OpenAPI schema then all detected endpoints will be considered new. This enables you to generate an OpenAPI schema based on the traffic received by your API.

The ⓘ icon shown above is present whenever a new API Endpoint is found that doesn't existing in an OpenAPI Schema associated with the API. This may be because it is a new Endpoint that has been added and the schema just hasn't been updated yet, it may be due to a bug or typo that is causing new traffic to not be associated with an existing API Endpoint or you may just not have an OpenAPI schema yet and want to use Speakeasy to generate it for you.

Whenever Speakeasy detects new Endpoints you can be alerted to their existence via a Webhook that you could integrate with Slack/Teams or any other system that will receive events via Webhooks.

Schema Generation

To help you bring your traffic and OpenAPI schema back into sync, the Speakeasy platform can help you update your schema by generating schemas for the new endpoints that have been detected.

To view the generated schema click on the ⓘ icon either next to an API or an API Endpoint. Clicking on the ⓘ icon next to an API will show you a diff with all the new API Endpoints for that API shown in the generated schema. Otherwise clicking on the ⓘ icon next to an API Endpoint will show you just the generated schema for that Endpoint.

The OpenAPI schema can then be downloaded by clicking the DOWNLOAD button at the bottom of the Schema Diff View. This will download a .yaml for your API that can then be refined as necessary and reuploaded to the Speakeasy platform.\ \ The downloaded schema will have _PLACEHOLDER_DESCRIPTION_ placeholders where documentation and descriptions of the Endpoints/types and parameters would normally be documented. You can replace this placeholders or delete them completely before reuploading.\

Uploading your new Schema

Now that you have generated a schema with your new API Endpoints present in it, this can be reuploaded to the Speakeasy platform and any of the Endpoints we had previously detected as being new will now be recognized as being a part of your schema and the ⓘ icon will disappear.

Coming soon

• The Speakeasy platform will not only detect new API Endpoints but changes to the schema of existing API Endpoints.
• Documentation for detecting, generating, downloading and uploading schemas via the Speakeasy API.