How to import the OpenAPI file and update it later?

[minaelee]

If you import an OpenAPI file through the Import content dialog instead of through an OpenAPI block, is there any way to update the source, aside from deleting it and reimporting it?

[jnewell7]

Lol

[aikoii]

👋 @minaelee, currently, it's the only way to update the source. I get that this might not be a very smooth way to do it, and appreciate your feedback 🙂

[TomOudeRengerink]

I had assumed that utilizing a URL as the OpenAPI source would automatically recognize updates in the file, but it seems this is not the case. Additionally, I've encountered an issue where this URL becomes cached within GitBook, preventing the updating of OpenAPI blocks since the cached contents of the URL are loaded instead. The only workaround I've found is to clear the cache by appending a query parameter to the URL, such as ?v=1.0.1.

@jpreynat, I'm wondering if there's a method to enable live updates from an OpenAPI source (URL) within our blocks?

[sarus]

The OpenAPI snippet is really useful. We'd love to be able to incorporate updating the source document as part of our CI/CD pipeline (our spec file is currently generated from our source as part of our pipeline). The simplest would be if GitBook could recognize changes in the source URL but having an ability to trigger an update via REST or some other mechanism would also be great (versus having to manually re-upload a new source document)

Thank you!

[TomOudeRengerink]

@jpreynat Any updates on this?

[James4David]

No, if you import an OpenAPI file directly through the "Import new pages" dialog by uploading a file, there is no way to update the source file via the UI other than deleting the resulting pages/blocks and re-importing the new version.

However, GitBook offers a much better, modern workflow for OpenAPI that allows for updating:

The Auto-Updating OpenAPI Workflow
To manage and update your OpenAPI specification without deleting and re-importing, you need to add it to your Organization's OpenAPI Section first, not directly into a space's pages.

Method 1: Update via GitBook UI (The Correct Way)
Add the Spec at the Org Level: Navigate to your Organization Settings and find the OpenAPI section in the sidebar.

Add a New Specification: When you add it here, you have two choices for updates:

From a URL: If you provide a hosted URL to your spec, GitBook will automatically check for updates every 6 hours. You can also manually trigger a refresh by clicking "Check for updates" in the OpenAPI settings panel.

From a File: If you upload the file here, you can later go back to the same panel and click the "Update" button to upload a newer version of the file, replacing the old one without affecting the pages in your documentation space.

Insert the Content: Once the specification is added to the organization, you insert it into your documentation pages using an OpenAPI block or by selecting "OpenAPI Reference" when adding a new page. The content in your docs will then pull from the central, updatable source.

Method 2: Use the GitBook CLI (For CI/CD Automation)
For teams that update their spec frequently (e.g., in a CI/CD pipeline), the GitBook CLI is the most powerful method:

You can use the command gitbook openapi publish with the file path or URL. This command will replace or update the existing specification in your GitBook Organization, automatically propagating the changes to any pages using that spec. This removes the need for any manual UI interaction entirely.