Publishing an API reference from an OpenAPI spec
Import your OpenAPI spec, review the endpoints it creates, and publish them as an API reference in your Help Center.
Written By Markus Palm
Last updated 12 days ago
Overview
An API reference gives every endpoint in your OpenAPI spec its own page in your Help Center. Import the spec, review the endpoints Featurebase finds, then publish them. Readers see nothing until you publish: the first import of a spec is always a draft, even when it comes from your CI pipeline.
Before you start, you need:
The Manage Help Center permission
An OpenAPI 3.0 or 3.1 spec in JSON or YAML, up to 50 MB, as a file or at a public URL
Note: Featurebase does not load other files that your spec references with $ref. If your schemas live in separate files, bundle the spec into one file first.
Publish your API reference
Open the API reference settings
If your Workspace has more than one Help Center, choose one in the Help center menu at the top of the page
Click 'Add API spec'
Import the spec
Each spec you import is one version of your API. Choose where it comes from:
Upload a file: A one-time import. To update the reference later, upload a new file
Link a URL: Featurebase reads the spec from a public URL and checks it for changes every 6 hours
Push from CI: Your pipeline sends each new version of the spec. You upload the current file once to start
To import it:
Click 'Upload a file', 'Link a URL', or 'Push from CI'
Drop your spec file in the upload area, or enter the address of the raw JSON or YAML file under Spec URL
Click 'Import'
Featurebase reads the API name and the version label from info.title and info.version in your spec. You can change both later in the version's Settings tab.
With Push from CI, the popup continues to Connect your pipeline, where you create an API key and copy the pipeline step. To finish later, click 'I'll do this later' and use the version's Source tab.
To publish a second API, import its spec and add it as a new API. For example, you can keep your Payments API separate.
Review the import
After the import, the version's page opens. A bar above the tabs shows how many endpoints Featurebase found and how many warnings the import produced. Check the result before you publish:
Endpoints tab: Lists every endpoint, grouped by tag. All endpoints are selected. Clear the checkbox of any endpoint that should not get a page
'Warnings': Opens the import report with the API title, version, OpenAPI version, servers, and every warning
'Preview': Opens the draft in your Help Center in a new tab. The line Draft preview. Only admins see this. at the top confirms that you see the draft and not the live pages
Warnings do not block publishing. Common ones are $refs to other files that were not loaded, a missing or relative server URL, and endpoints without a summary. When a warning affects readers, fix it in your spec and import it again.
Tip: To keep an endpoint out of every import, mark it with x-internal or x-excluded in your spec. An endpoint marked x-hidden gets a page that is not listed in the sidebar and opens only from its link.
What readers see
Your Help Center now has an API reference tab with a page for every endpoint you selected, grouped by tag. The tab sits after your other tabs by default. The first version you publish becomes your default version, the one readers see first.
You can rename or move the tab, or add guides such as an authentication article.
Fix import problems
When an import fails, Featurebase shows the reason. The most common messages:
Featurebase rejects a spec when more than 20% of its $refs point to other files. With fewer, the import works, but the referenced parts are missing, and the import report lists them as a warning.
Troubleshoot errors with a spec URL, such as a page that needs a login.
Next steps
Was this helpful?
Still need help? Ask the team