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 About 2 hours 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

Go to Settings → Help Center → API reference
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, as described in Updating your API reference from a URL or CI. To finish later, click 'I'll do this later' and use the version's Source tab.

To publish a second API, such as a separate Payments API, import its spec the same way and add it as a new API instead of a new version, as described in Managing API versions and multiple APIs.

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.

Publish the pages

Click 'Publish N pages' in the bar. The number counts the endpoints you selected.

To cancel instead, click 'Discard' and confirm. Featurebase removes the spec, and readers see no change.

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.

To rename or move the tab, or to add guides such as an authentication article, see Organizing the API reference tab.

Fix import problems

When an import fails, Featurebase shows the reason. The most common messages:

Message mentions	What to do
Swagger 2.0	Convert the spec to OpenAPI 3.0 or 3.1 with a converter tool, then import it again
OpenAPI ... is not supported	Save the spec as OpenAPI 3.0 or 3.1
Larger than 50 MB	Make the file smaller, for example by removing unused components and long examples
Not valid JSON or YAML	Fix the syntax error, then import the file again
Not an OpenAPI spec or document	Add the top-level `openapi` field, for example `openapi: 3.1.0`
No endpoints under "paths"	Add at least one endpoint under `paths`
Points to other files	Bundle the spec into one file, then import it again

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.

For errors with a spec URL, such as a page that needs a login, see Updating your API reference from a URL or CI.

Next steps

Updating your API reference from a URL or CI: Keep the reference in step with your API
Code samples and the API playground: Set up Try it and choose the example languages
Organizing the API reference tab: Name the tab, set its start page, and add guides

Still need help? Ask the team