Bug Fix: API Reference 'Show More' Button Issue

In this article, we will dive into a bug encountered in the API Reference component, specifically concerning the “Show additional properties” button. This button is designed to enhance user experience by limiting the number of properties displayed for schemas with numerous fields. We'll explore the motivation behind this feature, the current broken behavior, steps to reproduce the issue, expected behavior after the fix, and the verification process.

Motivation Behind Progressive Disclosure

The primary motivation for implementing the progressive disclosure pattern in the API Reference component is to improve readability and reduce visual clutter. When dealing with schemas containing a large number of properties, displaying all of them at once can overwhelm users and make it difficult to find the information they need. By initially showing a subset of properties and providing an option to expand and view all properties via a “Show additional properties” button, we can:

• Enhance Scannability: Users can quickly scan the most relevant properties without being distracted by the entire list.
• Reduce Cognitive Load: By presenting information in smaller chunks, we reduce the cognitive load on users, making it easier for them to understand the schema.
• Improve User Experience: A clean and scannable interface leads to a better overall user experience.

The “Show additional properties” button is a crucial element in achieving this progressive disclosure pattern. It allows users to access complete schema information when needed while maintaining a clean and scannable interface.

Current Broken Behavior: A Non-Functional Button

Currently, the “Show additional properties” feature is experiencing a bug where the button appears but does not function as expected. All properties are displayed by default, regardless of the button's state. Clicking the button does not change the visibility of the properties, creating a confusing user experience. The UI suggests interactivity that doesn't exist, defeating the purpose of the progressive disclosure pattern.

This broken behavior can lead to user frustration and a less efficient experience when navigating complex schemas. Users may struggle to find specific properties within the long list, and the visual clutter can make it difficult to grasp the overall structure of the schema.

Steps to Reproduce the Issue

To reproduce this bug, follow these steps:

1. Save the provided testopenapi.json file under the scalar/packages/api-reference/ directory.

   {
     "openapi": "3.0.1",
     "paths": {
       "/Test": {
         "post": {
           "summary": "Test",
           "operationId": "Test",
           "requestBody": {
             "content": {
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/TestRequest"
                 }
               }
             },
             "required": true
           },
           "responses": {
             "204": {
               "description": "No Content"
             }
           }
         }
       }
     },
     "components": {
       "schemas": {
         "TestRequest": {
           "required": [
             "A",
             "B",
             "C"
           ],
           "type": "object",
           "properties": {
             "A": {
               "maxLength": 50,
               "type": "string"
             },
             "B": {
               "maxLength": 50,
               "type": "string"
             },
             "C": {
               "maxLength": 50,
               "type": "string"
             },
             "D": {
               "maxLength": 50,
               "type": "string"
             },
             "E": {
               "maxLength": 50,
               "type": "string"
             },
             "F": {
               "maxLength": 50,
               "type": "string"
             },
             "G": {
               "maxLength": 50,
               "type": "string"
             },
             "H": {
               "maxLength": 50,
               "type": "string"
             },
             "I": {
               "maxLength": 50,
               "type": "string"
             },
             "J": {
               "maxLength": 50,
               "type": "string"
             },
             "K": {
               "maxLength": 50,
               "type": "string"
             },
             "L": {
               "maxLength": 50,
               "type": "string"
             },
             "M": {
               "maxLength": 50,
               "type": "string"
             },
             "N": {
               "maxLength": 50,
               "type": "string"
             },
             "O": {
               "maxLength": 50,
               "type": "string"
             },
             "P": {
               "maxLength": 50,
               "type": "string"
             },
             "Q": {
               "maxLength": 50,
               "type": "string"
             },
             "R": {
               "maxLength": 50,
               "type": "string"
             },
             "S": {
               "maxLength": 50,
               "type": "string"
             },
             "T": {
               "maxLength": 50,
               "type": "string"
             },
             "U": {
               "maxLength": 50,
               "type": "string"
             },
             "V": {
               "maxLength": 50,
               "type": "string"
             },
             "W": {
               "maxLength": 50,
               "type": "string"
             },
             "X": {
               "maxLength": 50,
               "type": "string"
             },
             "Y": {
               "maxLength": 50,
               "type": "string"
             },
             "Z": {
               "maxLength": 50,
               "type": "string"
             }
           }
         }
       }
     }
   }
   

2. Update the packages/api-reference/index.html file to include the OpenAPI spec created in step 1.

             {
               title: 'Bolt',
               url: 'https://assets.bolt.com/external-api-references/bolt.yml',
             },
             {
               title: 'OpenStatus',
               url: 'https://api.openstatus.dev/v1/openapi',
             },
   +          {
   +            title: 'Reproducing Issue',
   +            url: 'testopenapi.json',
   +          },
           ],
           persistAuth: true,
           // Avoid CORS issues
           proxyUrl: 'https://proxy.scalar.com',
         })
   

3. Run pnpm dev:reference to spin up the API Reference locally.

4. Click the dropdown on the top left and select Reproducing Issue.

5. Observe that the Show Additional Properties button is non-functional.

Expected Behavior: A Functional Toggle

The expected behavior is that when a schema has many properties, only a limited number should be displayed initially. The “Show additional properties” button should act as a toggle, controlling the visibility of the remaining properties. Clicking the button should:

• Expand the list to show all properties.
• Update the button text/state to reflect the expanded state (e.g., change the text to “Hide additional properties”).

This behavior ensures that users can easily access all the information they need while maintaining a clean and organized interface.

Acceptance Criteria

The following acceptance criteria must be met to consider the bug fixed:

• Initially, only a subset of properties should be visible.
• Clicking the “Show additional properties” button should expand the disclosure and reveal all properties.

Verification Process: Ensuring the Fix Works

To verify that the bug is fixed, we will use both manual and automated testing methods.

Manual Testing

1. Load the example OpenAPI document provided in the reproduction steps.
2. Navigate to the Reproducing Issue example.
3. Verify that initially only a limited number of properties are shown (not all 26).
4. Click the “Show additional properties” button.
5. Verify that all properties (A through Z) are now visible.
6. Confirm that the button state/text updates to reflect the expanded state.

Automated Testing

1. Run the test suite: pnpm test Schema.test.ts

Automated tests provide a reliable way to ensure that the fix remains effective over time and that no regressions are introduced in future updates.

Conclusion

Fixing the “Show additional properties” button bug is crucial for maintaining a user-friendly and efficient API Reference component. By implementing the progressive disclosure pattern correctly, we can improve the readability of complex schemas and enhance the overall user experience. The verification process, including both manual and automated testing, ensures that the fix is effective and reliable.

For more information on API design and best practices, visit https://swagger.io/.