Troubleshooting API documentation issues

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 the 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 that all API clients (e.g., Postman, cURL) 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 construct API request URLs manually.

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.

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.

Limitation: Descriptions and metadata defined in top-level OpenAPI tag objects are not displayed in the generated API documentation.

When an OpenAPI specification file contains top-level tags used to group API operations, Document360 converts those tags into folder-type categories during import. Folder categories are used only for organizing endpoints and do not generate standalone content pages. As a result, any description or metadata defined within those top-level tag objects is not rendered in the API documentation.

Workaround: Add the relevant context directly to the individual endpoint descriptions within the tag, so the information is visible on the generated endpoint pages.

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.

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.

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.

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.

Error: Unable to add API reference. This operation can’t be completed. Please ensure that you have given a valid specification file.

The possible cause might be that the uploaded specification file (YAML) may be malformed and not a valid OpenAPI 3.0 YAML. This often happens when the file is copied or exported from a rich-text editor, introducing formatting issues.

Steps to resolve:

1. Validate your spec file: Open your YAML file in a tool like Swagger Editor or a code editor to check for errors or formatting issues.

2. Look for unwanted formatting characters: Check for characters like \f0\fs24 or trailing backslashes \ that may have been introduced during copy-paste from a rich-text source. These can break the YAML format.

3. Clean up the file: Use a plain text or code editor to remove any special formatting characters. Avoid using word processors when editing or saving YAML files.

4. Re-upload the file: After cleaning the file and ensuring it’s a valid OpenAPI 3.0 YAML, try uploading it again.