Managing API documentation

Plans supporting 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 a 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 from the top navigation bar and select New API. This will display the New API reference window.

4. Select the Upload API definition option 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 to the New API reference window directly.

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.

NOTE

If you wish to verify your API documentation before publishing, click Close on the Finish screen to return to the Documentation screen. You will be able to see the drafts of your API documentation in the Categories & articles pane.

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 from the top navigation bar and select New API. This will display the New API reference popup.

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

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

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.

Regenerate API documentation

If you make any changes to your API, such as adding any endpoints, you do not need to manually update your API documentation in Document360. You can simply regenerate your API documentation, and any changes in your API will automatically reflect in the API 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 docs reference 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.

   2. 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 as per the API specification file in 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 docs reference 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 below command.

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.

Troubleshooting

Missing or incorrect server URL in OpenAPI

Error: This error occurs when the server URL is missing or incorrectly configured in the OpenAPI specification. As a result, API users do not know where to send API requests, and the "Try it" button may be unavailable in the API documentation. The root cause is typically a missing or incorrect servers section in the OpenAPI spec.

Steps to resolve

To resolve this issue, ensure that the OpenAPI specification includes the correct server URL:

1. Define the server URL in OpenAPI specification:

   servers:
     - url: https://apihub.document360.io
       description: Main API hub

2. For region-based APIs, define multiple server URLs:

   servers:
     - url: https://apihub.document360.io
       description: Global API hub
     - url: https://apihub.us.document360.io
       description: US region API hub

3. Ensure all API clients (Postman, cURL, etc.) use the correct server URL when making requests.

NOTE

The above URLs are examples. Please refer to your specific API configuration for the correct server URL.

Example:

YAML example for missing servers section:

paths:
  /users:
    get:
      summary: Retrieve a list of users
      responses:
        '200':
          description: A list of users
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    userId:
                      type: integer
                    userName:
                      type: string

To avoid this issue, ensure the servers section is properly defined in the OpenAPI specification to prevent API consumers from having to manually construct API request URLs.

401 unauthorized error from incorrect server URL

Error: This error occurs when API requests return a 401 unauthorized response. It typically happens when the incorrect server URL is used in API requests. For example, using https://apihub.document360.io instead of https://apihub.us.document360.io causes authentication failures.

Steps to resolve:

To resolve this issue, follow these steps to ensure correct server URL usage and proper authentication:

1. Ensure that API requests use the correct region-based endpoint.

2. Confirm that the correct client ID and client secret are being used.

Example of a correct API request:

GET https://apihub.us.document360.io/v2/Articles/{article_id}/en?appendSASToken=true

NOTE

The above URL is an example. Please refer to your specific API configuration for the correct server URL.

3. Ensure the authentication token is correctly included in the request headers.

Missing server URL in API documentation

Error: This issue occurs when API consumers are unsure which base URL to use for their requests. This typically happens when the documentation does not clearly state the server URL, even though it might be correctly configured in the OpenAPI specification.

Steps to resolve:

To prevent confusion and ensure API consumers know the correct base URL:

1. Specify the base URL explicitly in the API documentation.

Examples:

Comparison table: server URL present vs. missing

NOTE

The above URLs are examples. Please refer to your specific API configuration for the correct server URL.

To avoid this issue, ensure the API documentation clearly specifies the server URL to avoid any confusion.

403 error when using the “Try it” feature with an OAS file

Error:

After successfully uploading an OAS file, clicking on the Try it feature results in a 403 error. This error occurs when the OAS file is missing a definition for the BearerAuth security mechanism.

Steps to resolve:

To resolve the 403 error, follow these steps:

1. Check if the BearerAuth security definition is present in your OAS file.

2. If the BearerAuth definition is missing, include the BearerAuth security definition in the OAS file and reupload it.

3. During the import process, verify if any alerts related to Bearer Authentication are triggered and address them accordingly.

Incorrect HTML styling in API response

When retrieving an article’s HTML content through an API, the response is formatted in JSON, which uses escaping (\") to handle certain characters safely. This escaping alters characters like quotes, backslashes, and newlines to prevent data transmission errors. However, if the escaped characters are not converted back (unescaped), the HTML structure may break, leading to styling issues when rendered.

For example, a simple HTML paragraph:

<p>This is a "sample" paragraph.</p>

Might appear in the JSON response as:

"<p>This is a \"sample\" paragraph.</p>"

The escaped double quotes (\") ensure the JSON remains valid, but if not unescaped, the HTML might not render correctly.

Steps to resolve

1. Retrieve the HTML content via the API and inspect the response.

2. Look for escaped characters in the JSON response, such as:

   • \" (escaped double quotes)

   • \\ (escaped backslashes)

   • \n (newline)

   • \t (tab)

3. Unescape the JSON content before rendering it. This will restore the original HTML structure.

4. Verify the styling after unescaping to ensure the content appears correctly.

5. If the issue persists, check if additional modifications in your code are altering the API response.

   

   Once unescaped properly, the HTML will display as expected, preventing styling discrepancies.

Variables and Snippets not rendering in API response

When retrieving article content via the API, variables and snippets may appear unprocessed (e.g., {{variable.UserName}} instead of actual values). This typically happens when the "isForDisplay" parameter is not set correctly.

• If "isForDisplay" = true, the API will return the article content with all variables and snippets fully rendered. This means the placeholders are replaced with actual values, making the content suitable for display to end-users.

• If "isForDisplay" = false (or not set), the API response will contain unprocessed variables and snippets, which may not be useful for direct display.

  If the issue persists after following these steps, please contact the Document360 support team for further assistance: Contact Document360 Support

Article content in the Knowledge base:

Welcome, {{variable.UserName}}! Here’s how to use {{variable.ProductName}}.

API response without "isForDisplay":

"Welcome, {{variable.UserName}}! Here’s how to use {{variable.ProductName}}."

The variables remain unprocessed, making it unsuitable for direct display.

API response with "isForDisplay"=true:

"Welcome, John! Here’s how to use Document360."

Steps to resolve:

1. Retrieve the article content via API and inspect the response.

2. Check if variables or snippets appear unprocessed in the response.

3. Ensure the API request includes the "isForDisplay" parameter. If missing, modify the request to include "isForDisplay": true.

4. Send the modified API request. Example request:

   {
     "articleId": "12345",
     "isForDisplay": true
   }
   

5. Verify if the API response now displays the correctly rendered variables and snippets.

6. If the issue persists, ensure that the system processing the API response handles and displays the rendered content properly.

7. When updating articles via the API, do not pass fully rendered content to avoid replacing dynamic placeholders with static values.

Empty body shown in API documentation due to missing schema type

The API documentation displays an empty body. The possible cause for this error could be that the OpenAPI schema is missing the “type": "object” attribute in one or more object definitions.

Steps to resolve:

Ensure that every object definition in your OpenAPI specification includes “type": "object”. This attribute clearly specifies that the defined structure is an object, helping maintain clarity and consistency in your API documentation. It allows API documentation tools to accurately render request body parameters, response schemas, and other object definitions, making it easier for developers to understand and interact with your API.

Helpful links