Products
Attach documentation to a plan
Use a plan's Documentation tab to set a documentation level, add versions, choose how each version is sourced, and publish SDKs to subscribers.
You attach documentation to a plan on its Documentation tab. You first pick a documentation level, then add one or more documentation versions, choose how each version is sourced, and optionally publish SDKs for subscribers to download. Documentation is saved with the plan.
What are the documentation levels?
The level decides how documentation is organized on the plan. You pick one from a dropdown at the top of the Documentation tab.
| Level (label) | What it does |
|---|---|
| Plan level | One set of documentation versions shared across the whole plan. |
| API level | Documentation versions attached per API in the plan. |
| Custom level | Documentation versions that are not tied to a specific API. |
The Public access toggle sits next to the level dropdown. Turn it on to make the plan's documentation visible to anyone; leave it off to keep documentation visible to subscribers 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 versions under each API.
- Open your product, open the plan, and select the Documentation tab.
- Pick a level from the dropdown: Plan level, API level, or Custom level.
- Click + Add new version. At API level, add it under the API you want.
- Set the version label in the Version column. The selected radio marks the active version.
- Mark the version Deprecated or Beta in the Status column if needed, and use the eye icon to toggle its visibility.
- Click Save Changes on the plan.
At API level, if the plan has no APIs yet, the tab points you to the APIs tab to add them first.
How can a documentation version be sourced?
Each version has a retrieval type, set from a dropdown in the Documentation Entry column. It decides where the documentation comes from.
| Retrieval type (label) | Where the documentation comes from |
|---|---|
| Manual Upload | A spec file you upload to the version. |
| Gateway Synchronization | Pulled from your gateway. Available on AWS gateways. |
| Continuous Delivery | Pushed to the version from your CI/CD pipeline, using the version's ID and URL. |
| API Catalogue | Linked to an entry in your API Catalog. |
For Gateway Synchronization, the version shows a Fetch latest version button once the plan is saved and bound to an AWS gateway with APIs. Before the plan is saved it reads Save the plan first. If the gateway is not AWS, or the plan has no APIs, the version states the reason instead.
How do I publish an SDK?
Open a documentation version's SDKs column and choose + Add SDK. You either upload an SDK ZIP or generate one for a language, then set who can see it.
- On a documentation version with a valid spec URL, click + Add SDK in the SDKs column.
- In the Add SDK dialog, choose a Source: Upload an SDK ZIP, or Generate one for the languages you select.
- Pick the SDK Language. Generate accepts multiple languages; Upload takes one.
- Set Visibility to Public, Private, or Subscribers Only.
- For Upload, choose the ZIP under Upload SDK ZIP.
- Choose Save Changes in the dialog, then Save Changes on the plan.
Published SDKs are listed on the documentation version, and subscribers see the ones whose visibility allows it. The Add SDK button is disabled until the version has a valid documentation URL.
Troubleshooting
Match what the Documentation tab shows to the fix.
| What you see | What to do |
|---|---|
| At API level, a message pointing to the APIs tab | The plan has no APIs. Add APIs on the APIs tab, then return to add per-API documentation. |
| A Gateway Synchronization version reads "Save the plan first" | The plan is unsaved. Save the plan, then use Fetch latest version. |
| A Gateway Synchronization version states the gateway type is not supported | The plan's gateway is not AWS. Use Manual Upload, Continuous Delivery, or API Catalogue instead. |
| The + Add SDK button is disabled | The documentation version has no valid spec URL yet. Add a valid documentation source first. |
| A red mark next to a documentation version | The version's spec URL failed validation. Open the version and supply a valid spec. |
| The Documentation tab is read-only | The plan is archived, or you lack the manage-products role. |