Attach documentation to a plan

You attach documentation to a plan on its Documentation tab. A plan with no documentation yet opens on a short setup prompt. After that you choose a documentation level, add documentation versions, pick where each version comes from, and optionally publish SDKs. Documentation saves with the plan.

What happens when I first open the Documentation tab?

If the plan has no documentation yet, the tab asks How would you like to show the documentation? instead of showing the editor. Your answers set the documentation level and add the first version. You can change both later.

1. Open your product, open the plan, and select the Documentation tab.
2. Choose how to show the documentation:
   • Show the API specification for each API individually. Each API gets its own section.
   • Show one combined API specification for all APIs in this plan. The plan's APIs appear as one specification.
3. If you chose one combined specification, choose Continue, then pick where it comes from:
   • Build it for me. Apiable merges the plan's APIs' specifications. If some endpoints appear in more than one API, it keeps one and reports what it left out.
   • I'll provide the specification. You get an empty version to upload into now or later.
4. Set Publicly Accessible. See who can read the documentation.
5. Choose Finish, then Save Changes on the plan.

On a catalog-led portal, choosing each API individually adds a second question, Where should each API's documentation come from?: Follow the API Catalog. or I'll provide a specification for each API. If you provide your own and the plan's APIs come from the API Catalog, save the plan once before you upload the files. The prompt also shows when the API Catalog was last updated, with a Synchronize API Catalog button.

Choose Configure manually instead to skip the prompt and use the editor directly.

If the plan has no APIs yet, the tab says This plan has no APIs yet. Choose Add APIs to go to the APIs tab, or Set up documentation only to open the editor for a plan that carries documentation without APIs.

What are the documentation levels?

The level decides how documentation is organized on the plan. Pick it from the Documentation level dropdown at the top of the tab.

The Publicly Accessible toggle sits next to the dropdown.

Who can read a plan's documentation?

Publicly Accessible decides it. On, anyone can read the plan's documentation in your API Portal, signed in or not. Off, the API Portal shows it to signed-in users. New plans start with it on.

Turning it off does not limit the documentation to the plan's subscribers. Any signed-in user of your API Portal who can see the product can read it. Which products a developer can see is set by the product's visibility and audience.

The API Portal lists documentation for Active plans only.

How do I add a documentation version?

Pick a level, then add a version. At Plan and Custom level you add versions to the plan. At API level you add them under each API.

1. Open the plan and select the Documentation tab.
2. Pick a level from Documentation level: Plan, API or Custom.
3. Choose + Add new version. At API level, use the button under the API you want.
4. Set the version label in the Version column. The selected radio button marks the active version.
5. Tick Deprecated or Beta in the Status column if they apply, and use the eye icon to show or hide the version.
6. Choose a source in the Documentation Entry column (see the next section), then fill it in.
7. Choose Save Changes on the plan.

A new version starts as an empty Manual Upload. At API level, if the plan has no APIs yet, the tab points you to the APIs tab.

Where can a documentation version come from?

Each version has a source, chosen from the dropdown in its Documentation Entry column.

For Gateway Synchronization, the row shows Fetch latest version once the plan is saved and bound to an AWS gateway with APIs. Before the first save it reads Please save the plan to sync. If the plan has no gateway, a non-AWS gateway or no APIs, the row states the reason instead.

On a catalog-led portal the choices change. See How does documentation work on a catalog-led portal?.

How does Combined build one specification?

Combined (from plan APIs) merges the current specification of each API in the plan. The row says how many APIs it will combine, and Preview combined doc shows the result once the plan is saved and has APIs.

• An API contributes when it has a specification Apiable can read, from its API Catalog entry or its own documentation.
• An endpoint that appears in more than one API is kept once. The build report under the table, Some of this plan's APIs are not fully represented, lists what was left out and any API Not included at all, with the reason.
• Download this merge to edit gives you the merged file. Fix the overlaps and upload it as a Manual Upload version if you want full control.
• If none of the APIs' specifications can be read, the report says The combined specification could not be built. If the APIs have no specifications at all, the preview has nothing to show.

Combined versions take SDKs by upload only. Use the row's menu to download the combined file.

How do I publish an SDK?

Open a documentation version's SDK column and choose + Add SDK. Upload an SDK ZIP, or generate SDKs for one or more languages, then set their visibility.

1. On a documentation version that has a specification, choose + Add SDK in the SDK column.
2. In the Add SDK dialog, choose a Source: Upload or Generate. Combined versions offer Upload only.
3. Pick the language: Choose SDK Language (multiple) for Generate, Select SDK Language for Upload.
4. Set Visibility to Public, Private or Subscribers Only.
5. For Upload, choose the ZIP file under Upload SDK ZIP. It must be a ZIP file smaller than 10 MB.
6. Choose Save Changes in the dialog, then Save Changes on the plan.

In the API Portal, anyone can download a Public SDK, signed-in users can download a Private one, and a Subscribers Only SDK needs an active subscription to the plan. + Add SDK stays disabled until the version has a specification. Combined versions are the exception.

How does documentation work on a catalog-led portal?

Once your portal has switched to catalog-led documentation, each API in a plan can follow the API Catalog. A following API serves the catalog's latest specification version, or a version you pin, with the catalog's markers and SDKs.

See What does catalog-led documentation change? for the switch itself.

At API level

Each API is one row instead of a version table.

Choose Manual upload for an API to serve your own file instead. That API gets an empty version to upload into and stops following the catalog. You can switch any single API back to Follow the catalog later.

For an API taken from the API Catalog, choose Manual upload and save the plan before you upload the file. Then upload it and save again. A file uploaded in the same save as the switch to Manual upload is not kept.

A Catalog-bound API follows its catalog entry. A gateway API follows the catalog's copy of that gateway API, which exists for AWS APIs. An API the catalog holds no versions for keeps serving the plan's own documentation, and its row says it is not in the catalog.

In your API Portal, a following API offers its visible catalog versions in the version switcher, with the latest selected. A pinned API offers only its pinned version.

At Plan level

The sources are Generated, which merges the plan's APIs as served from the catalog, and Manual Upload. Gateway Synchronization, Continuous Delivery and API Catalogue are no longer offered. A version that already uses one of them keeps working, but you cannot choose that source again.

At Custom level

While the catalog manages the plan's documentation, the tab says The catalog manages versions for this plan, so there is nothing to add here. To version an API's documentation yourself, set that API to Manual upload at API level.

From CI/CD

Publish specifications to the catalog API, not to plan documentation. A pipeline that writes to a catalog API's plan documentation is refused, with a message that names the catalog endpoint. See How does CI/CD publish after the switch?.

Troubleshooting

Match what the Documentation tab shows to the fix.

Where to next