Configurable Sidebar: Show API Path Or Summary

Nov 17, 2025 by Alex Johnson 47 views

Issue #19 - [FEATURE] Add Configuration Option to Display Operation Path Instead of Summary in Sidebar

Navigating API documentation should be intuitive and efficient. Often, API documentation tools display operation summaries in the sidebar, which can become cumbersome when these summaries are lengthy. This proposal suggests adding a configuration option to display the operation path instead of the summary in the sidebar, offering users greater control over the presentation and improving overall usability.

Motivation

Existing API documentation tools typically rely on operation summaries to populate the sidebar navigation. This approach aims to provide users with a quick understanding of each endpoint's purpose. However, in practice, verbose or lengthy operation summaries can clutter the sidebar, making it difficult to scan and navigate efficiently. Imagine trying to find a specific endpoint in a long list of wordy summaries – it can be a frustrating experience. This issue becomes particularly pronounced in APIs with detailed documentation where operation summaries are comprehensive but also quite extensive.

The primary motivation behind this feature request is to enhance the usability of API documentation by providing users with the flexibility to choose between displaying operation summaries and operation paths in the sidebar. By allowing users to switch to operation paths, such as /planets/{planetId}, the sidebar becomes more concise and easier to scan, especially in APIs with verbose summaries like "Get a particular celestial body from the solar system currently classified as a planet." This configuration option empowers users to tailor the documentation to their specific needs, optimizing their workflow and improving their overall experience. The goal is to strike a balance between providing detailed information and maintaining a user-friendly interface. The choice between summaries and paths should cater to different user preferences and API documentation styles, ensuring that everyone can navigate the documentation efficiently.

Providing a configuration option to display the operation path (e.g., /planets/{planetId}) instead of the summary (e.g., "Get a particular celestial body from the solar system currently classified as a planet") would give users control over sidebar presentation. This improves usability for APIs with verbose documentation while maintaining backward compatibility for those who prefer summary-based navigation. The key is to offer a seamless and intuitive way for users to switch between these two modes, ensuring that the documentation remains accessible and informative regardless of the chosen configuration. By implementing this feature, we aim to create a more versatile and user-centric API documentation experience, ultimately benefiting both developers and consumers of the API.

Current Behavior

Currently, the API reference sidebar exclusively displays the operation summary for each endpoint. There is no existing mechanism or configuration option to alter this behavior and display the operation path instead. This limitation can lead to a cluttered and difficult-to-navigate sidebar, especially when dealing with APIs that have detailed and verbose operation summaries. The lack of customization options forces users to rely solely on summaries, even when paths might be more efficient for quick scanning and identification of endpoints.

Here's a step-by-step breakdown of the current behavior and how to reproduce the issue:

Load an OpenAPI specification with verbose operation summaries: To demonstrate the problem, you'll need an OpenAPI specification that includes detailed and lengthy operation summaries. For instance, you can modify the existing Galaxy API example to include a summary like "Get a particular celestial body from the solar system currently classified as a planet" for the /planets/{planetId} endpoint. This will serve as a good example of a verbose summary that can clutter the sidebar.
Open the API reference documentation and observe the sidebar: Once you've loaded the OpenAPI specification, open the API reference documentation and carefully examine the sidebar. You'll notice that the sidebar displays the full operation summary text for each endpoint.
Observe: The sidebar displays the full operation summary text, making it lengthy and difficult to scan. This is the core issue that this feature request aims to address. The long summaries take up significant vertical space, making it harder to quickly find the endpoint you're looking for. The overall readability of the sidebar is compromised, leading to a less efficient navigation experience.
Attempt to find a configuration option to display paths instead of summaries: Next, try to locate a configuration option or setting that allows you to switch the sidebar display from operation summaries to operation paths. Look for any settings related to sidebar appearance, navigation, or display preferences.
Observe: No such configuration option exists. This confirms the current limitation and highlights the need for the proposed feature. The absence of a configuration option prevents users from customizing the sidebar to their preferences, forcing them to deal with the default summary-based display.

This lack of flexibility can be particularly problematic for users who are already familiar with the API's structure and prefer to navigate using paths rather than reading through lengthy summaries. The current behavior limits the usability of the API documentation and hinders the efficiency of developers who rely on it.

Expected Behavior

The expected behavior is that users should have the ability to configure whether the sidebar displays operation summaries or operation paths. This configuration option should provide a simple and intuitive way to switch between the two display modes, allowing users to tailor the documentation to their specific needs and preferences. When configured to use paths, the sidebar should display the endpoint path (e.g., /planets/{planetId}) instead of the summary text, resulting in a more concise and easier-to-scan navigation experience. This change would significantly improve the usability of the API documentation, especially for APIs with verbose operation summaries.

To ensure a smooth transition and maintain backward compatibility, the default behavior should remain unchanged, meaning that the sidebar continues to display operation summaries unless the user explicitly configures it to display paths. This approach ensures that existing users are not disrupted by the new feature and can continue to use the documentation as they always have. The new configuration option should be clearly documented and easily accessible, allowing users to discover and utilize it without difficulty.

The implementation of this feature should also include proper typing and validation across all integration layers to ensure that the configuration option is correctly handled and that the sidebar display is consistent and accurate. Tests should be implemented to verify both the default behavior (displaying summaries) and the new path-based display option, ensuring that the feature works as expected and does not introduce any regressions. These tests should cover various scenarios and edge cases to guarantee the robustness and reliability of the implementation.

In essence, the expected behavior is to provide users with a simple yet powerful configuration option that empowers them to customize the sidebar display according to their preferences, ultimately enhancing the usability and efficiency of the API documentation. This feature should be seamlessly integrated into the existing documentation framework, providing a smooth and intuitive user experience.

Acceptance Criteria:

The successful implementation of this feature requires meeting the following acceptance criteria, ensuring that the new configuration option is properly integrated and functions as expected:

[ ] A new configuration option is available that controls whether the sidebar displays operation summaries or paths: This is the core requirement of the feature. The configuration option should be easily accessible and clearly labeled, allowing users to understand its purpose and how to use it.
[ ] The default behavior remains unchanged (displays summaries) to maintain backward compatibility: To avoid disrupting existing users, the default setting should be to display operation summaries. This ensures that the documentation continues to function as it always has unless the user explicitly changes the configuration.
[ ] When configured to use paths, the sidebar displays the operation path for each endpoint: This is the primary functionality of the new feature. When the configuration option is set to display paths, the sidebar should accurately show the endpoint path (e.g., /planets/{planetId}) instead of the summary text.
[ ] The configuration option is properly typed and validated across all integration layers: To ensure data integrity and prevent errors, the configuration option should be properly typed and validated. This includes validating the input format and ensuring that the value is within the expected range.
[ ] Tests verify both the default behavior and the new path-based display option: Comprehensive tests should be implemented to verify that both the default behavior (displaying summaries) and the new path-based display option function correctly. These tests should cover various scenarios and edge cases to ensure the robustness of the implementation.
[ ] Documentation clearly explains the new configuration option and when to use it: Clear and concise documentation should be provided to explain the new configuration option, its purpose, and how to use it. The documentation should also provide guidance on when to use paths instead of summaries, helping users make informed decisions about their sidebar display preferences.

Verification

To ensure the successful implementation of this feature, thorough verification is essential. This verification process should include both manual testing and automated tests to cover various scenarios and ensure the functionality works as expected.

Manual Testing:

Configure the API reference to use the default setting (or omit the configuration): Begin by configuring the API reference to use the default setting, which should be to display operation summaries. Alternatively, you can omit the configuration altogether, as the default behavior should be to display summaries.
Load an OpenAPI specification and verify the sidebar displays operation summaries: Load an OpenAPI specification with verbose operation summaries and verify that the sidebar correctly displays the summaries for each endpoint. This confirms that the default behavior is functioning as expected.
Configure the API reference to display operation paths: Next, configure the API reference to display operation paths instead of summaries. This involves changing the configuration option to the appropriate setting that enables path-based display.
Reload the same OpenAPI specification and verify the sidebar now displays operation paths instead of summaries: Reload the same OpenAPI specification and verify that the sidebar now displays operation paths instead of summaries. This confirms that the new configuration option is working correctly and that the sidebar is displaying the paths as expected.
Test with an API that has very long operation summaries to confirm the sidebar is more concise when using paths: To further validate the effectiveness of the new feature, test it with an API that has very long operation summaries. Confirm that the sidebar is more concise and easier to scan when using paths instead of summaries. This demonstrates the practical benefits of the feature in real-world scenarios.

By following these manual testing steps, you can thoroughly verify that the new configuration option is functioning correctly and that the sidebar is displaying the appropriate information based on the user's configuration. In addition to manual testing, automated tests should also be implemented to ensure the long-term stability and reliability of the feature.

In conclusion, this enhancement offers a significant improvement to API documentation usability. For further reading on API documentation best practices, consider visiting the Swagger documentation guide.