API Portal
API spec viewer and validation
Tune how the OpenAPI reference viewer behaves in your API Portal, and validate specs against a Spectral ruleset. Spec validation is entitlement-gated.
Two settings shape how OpenAPI specs behave in your API Portal. API Specifications controls the reference viewer your developers read. API Validation checks your specs against a Spectral ruleset. The viewer is open to anyone who can manage portals; validation is entitlement-gated. For the wider portal, see the API Portal overview.
How do you configure the API spec viewer?
Open Settings, then Portal Settings, then API Specifications. The page is a set of toggles and two endpoint options that change how the reference viewer renders. Set what you want, then choose Save changes.
| Setting | What it controls |
|---|---|
| Show Getting Started | Shows a getting-started section. Turning it on reveals a Getting started text field for its content. |
| Show AI Resource Center | Shows the AI resource center in the viewer. |
| Show Settings | Shows the viewer's own settings controls to developers. |
| Show Schema | Shows the schema by default. |
| Show Bypass Cors | Shows the bypass CORS option in the viewer. |
How do you set how endpoints are listed and ordered?
In API Specifications, two radio options control the endpoint list. One sets the label each endpoint shows; the other sets the order. Choose your options, then Save changes.
| Option | Choices |
|---|---|
| Endpoint label | Name or Url. |
| Endpoint order | Sorted Alphabetically, or Do not sort, use the order from the specification. |
How do you validate OpenAPI specs against a Spectral ruleset?
Open Settings, then Portal Settings, then API Validation. Set the validation type to Spectral, paste the URL of your Spectral ruleset, then choose Save changes. The URL is checked when you leave the field, and the save button stays disabled until the ruleset validates.
- Open Settings, then Portal Settings, then API Validation.
- Set the validation type. Spectral is the validation type Apiable supports.
- Paste your Spectral ruleset URL.
- Move focus off the field. Apiable validates the ruleset at that URL.
- Choose Save changes. The button enables once the ruleset is valid.
Why does my Spectral ruleset URL fail to validate?
The URL is checked when you leave the field, and the message tells you which problem it hit. The most common cause is a GitHub link to the repository page rather than to the raw file.
| What you see | What to do |
|---|---|
| A raw-URL error on a GitHub link | Point the URL at the raw file, not the repository page. |
| A generic invalid-ruleset error | Confirm the URL is reachable and returns a valid Spectral ruleset, then try again. |
| Save changes stays disabled | The ruleset has not validated yet. Fix the URL so the check passes. |
Where to next
API Portal overview
How pages, theme, navigation, and settings make up your portal.
Attach documentation to a plan
Add documentation versions and SDKs to a plan from your spec.
Custom CSS and Markdoc partials
Restyle the portal and reuse content blocks across products.
API reference
Browse the Apiable platform API used to manage portals and products.