Managing API references

This article covers everything you need to manage your API references in Document360. Creating new references, keeping them in sync with your spec, and using the available actions to view, edit, publish, and organize your API documentation.

API references list

The API references list gives you a central view of all configured API references in your workspace. To access it, navigate to API documentation ({ }) in the left navigation bar and click API references in the left navigation pane.

From here you can see the name, type, and last updated date for each reference. You can also create a new API reference by clicking New API in the top right corner.

Create a new API reference

To create a new API reference, click the Create dropdown in the top navigation bar and select New API. This opens the New API reference window where you have four options:

• Upload API definition - Upload a JSON, YAML, or YML spec file directly from your device or from Document360 Drive.
• Create from URL - Fetch your spec automatically from a hosted URL.
• CI/CD Flow - Integrate with your pipeline to update documentation automatically on every spec change. Requires Node.js.
• Try sample Pet Store API file - Use Document360's sample spec file to explore the workspace before uploading your own.

Upload API definition

1. Select the Upload API definition radio button.
2. Click Upload from my device to upload from your local storage, or Choose from Drive to select a file from Document360 Drive. You can also drag and drop your file directly into the window.
3. Document360 parses the file and generates the API reference. If warnings are detected, expand the Alerts and Warnings section to review them.
4. Click New API reference to proceed to the publish confirmation window.

Create from URL

1. Select the Create from URL radio button and click Next.
2. Enter the URL pointing to your OpenAPI specification file.
3. Click New API reference. Document360 fetches and processes the spec.

CI/CD flow

The CI/CD flow lets you keep your API documentation automatically in sync with your spec. Instead of manually uploading a new spec every time your API changes, you integrate the Document360 CLI into your pipeline so documentation updates automatically on every spec change.

For full setup instructions, see the CI/CD integration article.

API reference actions

Once an API reference is created, click the More (⋯) icon next to it in the API references list to access the following actions:

Keeping your documentation in sync

When your API changes - new endpoints added, parameters updated, responses modified, but you do not need to update your documentation manually. Regenerating your API reference pulls in all changes from your spec automatically.

Resync from an existing URL

1. In the API references list, click the More (⋯) icon next to the reference you want to update.
2. Click Resync. The documentation regenerates from the latest version of the spec at the existing URL.

Update to a new URL

1. Click the More (⋯) icon next to the reference.
2. Click Edit.
3. Enter the new URL in the URL field.
4. Click Update.

Regenerate from a spec file

1. Click the More (⋯) icon next to the reference.
2. Click Edit.
3. Upload the latest spec file in JSON, YAML, or YML format.
4. Click Update.

Resync via CI/CD

If your API reference was set up with the CI/CD flow, resyncing happens automatically as part of your pipeline whenever your spec changes. You can also trigger a manual resync using the apidocs:resync command:

d360 apidocs:resync \
  --apiKey=YOUR_API_KEY \
  --userId=YOUR_USER_ID \
  --apiReferenceId=YOUR_API_REFERENCE_ID \
  --path=PATH_TO_SPEC_FILE

For full details on setting up and managing the CI/CD flow, see the CI/CD integration article.

Automatic vs manual resync

If you generated your API documentation from a URL or a file, it will not update automatically. To have documentation update automatically, integrate with the CI/CD flow.

Understanding endpoint deletion during resync

When you update your API specification file, any endpoints that are no longer present in the new spec are permanently deleted along with any custom content added to those endpoint pages.

To update your spec file safely:

1. Upload the updated spec file in the Edit API reference window.
2. If any endpoints are deleted, a warning is displayed. Click Show deleted endpoints to review the list of affected endpoints.
3. Select the Confirm to continue checkbox to acknowledge the deletion.
4. Click Update to proceed.

Deleted endpoints are moved to the Recycle bin, where they can be previewed for up to 30 days but cannot be restored.

Keeping documentation in draft

After uploading or resyncing a spec, you can keep the resulting documentation in draft mode rather than publishing it immediately.

• In the publish confirmation window, click Close instead of Publish. All generated articles will remain in draft mode.
• Draft articles are visible in the Categories & Articles pane in the portal but are not accessible to readers on the Knowledge base site.
• You can review, edit, and add custom content to draft articles before publishing.

Nested categories

Document360 supports up to three levels of subcategories in the API documentation workspace. Categories are created based on the tag definitions in your spec file.

To create nested categories, use the > symbol in your OpenAPI tags:

tags:
  - name: "Pets > Details"

This creates a Pets category with a Details subcategory inside it. This structure is preserved during resync.

Category ordering

The order in which categories appear in your documentation matches the tag order defined in your spec file. To change the category order, reorder the tags array in your spec and resync.

Category options

Right-clicking a category in the Categories & Articles pane gives you the following options:

FAQ

Helpful links

• d360 npm package
• d360 source code