Add an OpenAPI specification

Learn how to add and update an OpenAPI specification in GitBook application or from CLI.

We’re currently improving how you build API documentation in GitBook. This page covers features that are being gradually rolled out. If you don’t see them yet, hang tight—they’re on the way!

If you have an OpenAPI spec, you can add it to your organization by uploading the file directly, linking to a hosted URL, or using the GitBook CLI.

How to add a specification

1. Open the OpenAPI section in the sidebar

2. Click on Add specification

3. Give your specification a name. This helps identify it, especially if you manage multiple specs

4. Choose one of the following:

   • Upload a file (e.g. openapi.yaml)

   • Enter a URL to a hosted spec

   • Use the CLI to publish the spec

Add an OpenAPI specification modal.

Update your specification

You can update your OpenAPI specification at any time using the GitBook UI or the CLI, regardless of how it was initially added.

In GitBook Application

In the OpenAPI panel:

• If your spec is linked to a URL:

  • GitBook checks for updates automatically every 6 hours.

  • To fetch updates immediately, click Check for updates.

• If your spec was uploaded as a file:

  • Click Update to upload a new version.

• You can switch from a File to a URL source by clicking on Edit in the breadcrumb actions menu.

Using the CLI

Use the same command to update your specification:

gitbook openapi publish --spec api-spec-name --organization organization_id <path-or-url>

You can also use the CLI to Check for updates by running the publish command on the same URL.

Read our Integrating with CI/CD guide to learn how to automate the update of your specification.