Managing API documentation

The API documentation feature in Document360 makes it easy to create clear, interactive documentation by uploading your API specification files. This process automatically builds detailed documentation that covers everything from API endpoints to methods and responses, helping developers understand and use your API more effectively.  

Generating API documentation

There are three methods to generate API documentation in Document360:

• From a URL

• From a JSON/YAML/YML file

• With a CI/CD flow

NOTE

Document360 supports OpenAPI 2.0, OpenAPI 3.0, OpenAPI 3.1, and Postman API specifications.

Generating API documentation from an API specification file

To generate API references from an API specification file (JSON/YAML/YML),

1. Navigate to the desired project in the Knowledge base portal.

2. Select API documentation ({ }) from the left navigation bar.

3. Click the Create dropdown in the top navigation bar and select New API. This will display the New API reference window.

4. Select the Upload API definition radio button in the New API reference window.

5. Click either Upload from my device or Choose from Drive to select the file from your device or Document360 Drive, respectively. You can also drag and drop your file directly into the New API reference window.

NOTE

The API documentation import process supports second-level subcategories using the > symbol in OpenAPI tags (e.g., Pets > Details). This allows for cleaner, nested organization of endpoints, preserves the structure during resync, and ensures proper display and navigation in the left panel of the API reference.

If your uploaded file has any associated alerts or warnings, you can view them by expanding the Alerts and Warnings dropdowns, which appear in the New API reference window.

6. Click New API reference to navigate to the Publish confirmation window. You will see a success message in the window, along with the number of categories and articles that have been created.

7. Click Publish to generate your API documentation.

NOTE

To review your documentation before publishing, click Close to return to the Documentation screen. Your draft will be visible in the Categories & Articles pane.

Generating API documentation from a URL

To upload the API specification file as a URL to Document360,

1. Navigate to the desired project in the Knowledge base portal.

2. Select API documentation ({ }) from the left navigation bar.

3. Click the Create dropdown from the top navigation bar and select New API or click the New API button from the top right corner. This will display the New API reference panel.

4. In the Choose source screen, select the Create from URL radio button, and click Next.

5. In the Source settings screen, enter the URL for your API specification file in the URL field.

6. Click Add API reference to navigate to the Finish screen.

7. On the Finish screen, you will be able to see the number of categories and articles that have been created for your API specification file.

8. Click Publish to generate your API documentation.

Generating API documentation with a CI/CD flow

Before you upload an API specification file with a CI/CD flow, ensure that the latest version of Node.js is installed on your system. If you are unfamiliar with Node.js, refer to this guide for installation instructions.

To upload the API specification file with a CI/CD flow,

1. Navigate to the desired project in the Knowledge base portal.

2. Select API documentation ({ }) from the left navigation bar.

3. Click the Create dropdown in the top navigation bar and select New API. This will display the New API reference window.

4. In the Choose source screen, select the CI/CD Flow radio button.

5. Copy the full CLI command shown from the New API reference window.

6. In the copied command, update the --path value with:

   • The full path to your local JSON/YAML/YML spec file. For example,

     --path=/Users/yourname/projects/api/openapi.yaml

   • A valid URL pointing to your API spec file. For example,

     --path=https://example.com/api/openapi.yaml

7. Paste the updated command in your terminal and press Enter.  

8. Your API specification file will be uploaded, and API documentation will be generated.

NOTE

• The first line (npm install d360 -g) installs the Document360 CLI tool. You only need to run it the first time. If it's already installed, you can skip that line.

• If you regenerate the API key by clicking the () icon in the UI, you must update the --apiKey value in your CLI command before running it again. The old key will no longer be valid.

Managing webhooks (events)

When your OpenAPI 3.1 spec includes webhooks, Document360 imports them and shows an event icon next to each webhook. The page displays the payload schema and example. If the spec does not include an example, a default example and a sample payload are shown. Try it is not available for webhooks. Webhooks are included in resync operations, and your custom content is retained after regeneration.

Regenerate API documentation

If you make any changes to your API, such as adding new endpoints, you do not need to update your API documentation in Document360 manually. You can regenerate your API documentation, and any changes to your API will be automatically reflected in the updated documentation.

NOTE

Any custom content you add to your API documentation will be retained when you regenerate your API documentation.

Regenerate API documentation from URL

1. Navigate to the desired project in the Knowledge base portal.

2. Select API documentation ({ }) from the left navigation bar.

3. Click API references from the left navigation list pane.

4. Click the More () icon next to the desired API reference for which you want to regenerate the API documentation.

   1. To regenerate API documentation from the existing URL:

      • Click Resync.

      • The API documentation will be regenerated as per the latest API specification file.

   

   1. To regenerate API documentation with a new URL:

      • Click Edit.

      • Enter the new URL in the URL field.

      • Click Update.

      • The API documentation will be regenerated according to the API specification file at the new URL.

Regenerate API documentation from an API specification file

1. Navigate to the desired project in the Knowledge base portal.

2. Select API documentation ({ }) from the left navigation bar.

3. Click API references from the left navigation list pane.

4. Click the More () icon next to the desired API reference for which you want to regenerate the API documentation.

5. Click Edit.

6. Upload the latest API specification file in JSON/YAML/YML format.

7. Click Update. The API documentation will be regenerated as per the latest API specification file.

Regenerate API documentation integrated with CI/CD flow

You can resync the API reference in your CI/CD pipelines with the help of your d360 npm packages. D360 is the command line tool that helps you set up workflows that sync your API docs to Document360.

You can also perform the resync manually using the command below.

d360 apidocs:resync 
                    --apiKey=API_key_value
                    --userId=user_id_value
                    --apiReferenceId=API_reference_value
                    --path=Spec_file_path

Download API reference

NOTE

To download the API files, ensure that the Show download API reference toggle in the Knowledge base portal settings is turned on.

Helpful links