API Portal
API spec viewer and validation
Tune the API reference viewer in your API Portal, including what the Bypass CORS option sends through Apiable, and validate your OpenAPI specs against a Spectral ruleset, with results in the API Catalog. Spec validation depends on your plan.
Two settings shape how OpenAPI specs behave around your API Portal. API Specification controls the reference viewer your developers read and test from. API Validation checks your specs against a Spectral ruleset. Validation depends on your plan. For the wider portal, see the API Portal overview.
How do you configure the API spec viewer?
Open Settings, Portal settings, API Specification. Five sections have a toggle, and two more set how endpoints are listed. Change what you want, then choose Save Changes. Your choices apply to every API reference on the portal.
| Section | Toggle | What it does |
|---|---|---|
| Show getting started section | Show Getting Started | Shows your Getting started text, written in Markdown, at the start of the reference. Nothing shows while the text is empty. |
| Show AI resource center | Show AI Resource Center | Shows a card at the start of the reference with the specification's address and buttons to download or open it. |
| Show settings modal for customers. | Show Settings | Gives developers a settings window to change these viewing options in their own browser. Your choices stay the defaults. |
| Schema | Show Schema | Shows schemas in the reference's sidebar by default. |
| Show bypass CORS | Show Bypass Cors | Adds a Bypass CORS checkbox to the request panel. See the next section before you turn it on. |
What does Bypass CORS send through Apiable?
When Show Bypass Cors is on, the reference's request panel shows a Bypass CORS checkbox that starts ticked. While it is ticked, each test request is sent to Apiable's proxy, which calls your API for the developer, instead of going straight from their browser to your API.
That includes everything the request carries: its headers, the API key or token the developer entered, and the request body. Token requests made from the reference, with their client credentials, go through the proxy too. Developers can untick Bypass CORS to call your API directly, which works only if your API allows requests from the portal's address.
Leave Show Bypass Cors off if test traffic and credentials must not pass through Apiable. Turn it on if developers cannot call your API from the browser because of cross-origin restrictions.
How do you set how endpoints are listed and ordered?
Under Endpoint listing, one choice sets the label each endpoint shows and the other sets the order. Choose your options, then choose 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, Portal settings, API Validation. Keep the validation type, paste the address of your Spectral ruleset in Ruleset URL, and choose Save Changes. The address is checked when you click out of the field.
- Open Settings, Portal settings, API Validation.
- Under Select validation type, keep SPECTRAL, the only type offered.
- Paste the address of your ruleset in Ruleset URL. It must return the ruleset as JSON or YAML.
- Click out of the field. The ruleset is fetched and checked.
- Choose Save Changes.
Where do validation results appear?
In Catalog, API Catalog, where the ruleset runs against each API's specification. Each API in the list shows a validation indicator, and its Specification tab lists the findings. See API Catalog, which also depends on your plan.
Why does my Spectral ruleset URL fail to validate?
The message under Ruleset URL tells you which problem it found. The most common cause is a GitHub link to the repository page rather than to the raw file.
| What you see | What to do |
|---|---|
| "It looks like you've linked to the GitHub page instead of the raw file." | Open the ruleset on GitHub, choose Raw, and use that address. |
| "Could not validate a spectral ruleset from the URL. Please ensure that the URL can be reached and that it contains a valid Spectral ruleset." | Check that the address is public and returns a valid Spectral ruleset. |
| Save Changes stays disabled | Nothing has changed, or the ruleset has not passed the check yet. |
| "Please upgrade to access this feature" | Your plan does not include API validation. Talk to sales. |
Where to next
API Catalog
Where each API's specification and validation results live.
Attach documentation to a plan
Add the documentation developers read in the viewer.
Trying endpoints in the explorer
What testing from the reference looks like for developers.
API Portal overview
How pages, theme, navigation, and settings make up your portal.