Manage your OpenAPI specs with Speakeasy.

In this guide we will walk you through the process of managing your OpenAPI specs using the Speakeasy API Registry and CLI. This is colloquially also known as a “source-only workflow” as it only utilises the sources feature of Speakeasy workflows.

Prerequisites

• A Speakeasy account and CLI installed. Log in here  to get an account created.
• An OpenAPI spec for your API

Overview

To get started create a github repository. Something like company-specs or company-openapi or common repository names.

Initialise a new workflow file by running speakeasy configure sources and follow the prompts to add in your OpenAPI spec and any Overlays you have. Make sure to give your source a meaningful name as this will be then name used for the API Registry in your workspace dashboard.

A common repository structure will look like the following:

The workflow file will be generated in the .speakeasy folder and will look like the following:

Publishing spec changes

Any time you would like to publish a new version of your OpenAPI spec to the API Registry simply run

This will publish the spec to the API Registry as a new revision for the source my-api.

You can also optionally tag the revision of a spec by running:

This will tag the most recent revision of the spec with the tag v1.0.0.

API Registry

This will show up as the latest revision in your API Registry tab in the dashboard.

You can leverage this to:

• Track changes to your spec, view detailed change reports and download past versions of the spec.
• Create a stable public URL for sharing a paritcular revision of the spec..
• Use the registry URI as a source for generating SDKs, eg: registry.speakeasy.com/your-company/your-company/my-api.