@W-20242139 OpenAPI Tags-Based Endpoint Grouping Support

[alexpmule]

OpenAPI Tags-Based Endpoint Grouping Support

Bug Report

Work ID: W-20242139

Issue Description:
The "tags" property defined at the operation level in OpenAPI specifications was not being rendered in the API Console. Users utilize the tags property to logically group related operations, which displays properly in Swagger Editor but was completely absent in API Console Builder (ACB). This created a usability gap where API consumers could not see the intended logical organization of operations.

Solution Overview

This update adds full support for rendering and grouping API endpoints by their OpenAPI tags in the API summary component. When operations share common tags, they are now displayed together with the tag name and description prominently shown, matching the expected behavior from tools like Swagger Editor.

Core Functionality

New Helper Methods

_computeEndpointName(endpoint, webApi, ops)
Determines the display name for an endpoint following a priority hierarchy. Returns an object with name and description properties, or undefined to fallback to the path.

_getEndpointTagInfo(endpoint, webApi)
Extracts tag information from endpoint operations. When multiple operations share tags, it identifies the most common tag and retrieves its description from the API definition. This enables meaningful grouping of related operations.

_getEndpointOperationName(endpoint)
Uses the operation summary as the endpoint name, but only when the endpoint has exactly one operation. This prevents inappropriate use of single operation summaries for multi-operation endpoints.

Name Resolution Priority

The component follows a clear hierarchy when determining endpoint display names:

• Explicit endpoint name: If the endpoint model includes a direct name property, use it
• Tag-based naming: Extract and use the most common tag from the endpoint's operations, including its description
• Operation summary: For single-operation endpoints, use the operation's summary
• Path fallback: When no other option is available, display the endpoint path

Template Updates

Endpoint with Name

When an endpoint has a resolved name (including from tags), the component displays:

• A paragraph containing the name (bold) and description (italic) if available
• The endpoint path as a clickable link below

Endpoint without Name

When no name is resolved, the component displays only the endpoint path as before, maintaining backward compatibility.

Styling

.endpoint-name-description
Container for the name and description block with controlled spacing and font size. Customizable via CSS custom properties.

.endpoint-name
Bold text for the endpoint name with themeable color properties for consistency with the design system.

.endpoint-description
Italic text for the tag description with subdued coloring to differentiate from the primary name.

Testing

Updated Existing Tests

Modified existing endpoint rendering tests to match the new HTML structure where endpoints display names separately from paths.

New Test Suite: Tags-based Endpoint Grouping

Comprehensive test coverage for the tags-flights demo spec, validating:

• Correct number of endpoint groups rendered
• Tag names displayed accurately for each endpoint
• Tag descriptions shown when available
• Endpoint paths preserved and accessible
• Operation counts match the specification
• HTTP methods rendered correctly for each group

Tests run in both Full AMF model and Compact AMF model modes to ensure compatibility with both formats.

Demo Integration

Added a new demo API specification tags-flights.yml showcasing the tag grouping feature with a flights API example. The demo includes two tag groups (AllFlights, OneFlight) with multiple operations demonstrating realistic usage patterns similar to what users would create in their own OpenAPI specifications.

Backward Compatibility

Endpoints without tags or explicit names continue to display using their paths as before. The changes are additive and non-breaking for existing API specifications.

Impact

This enhancement resolves the usability gap between API Console and other OpenAPI tools, allowing API designers to leverage tags for logical operation grouping as intended by the OpenAPI specification. Users can now see their APIs organized the same way across different tools, improving the overall developer experience.