elements
elements copied to clipboard
stoplightio
Expose description headings as separate sections in the nav
User Story
As an API consumer reading the definition I want to see the headings within the description So I can quickly get to the auth section
Acceptance Criteria
-
Only for API Component
-
If there is content in info.description before a header, it goes under the Overview header.
-
If there is a top level header then override Overview.
-
If headings exist in the API definitions top level description
- The overview nav title had child elements populated
-
if there are multiple top level headers, treat them all equally.
- eg: multiple H1s, add them all as links in TOC
- eg: multiple H2s, add them all as links in TOC
- eg: multiple H3s, add them all as links in TOC
- eg: if only one h1 and 10 h3s then we only show the h1 in ToC
Note, the headings are already anchor tags which helps!
Side by side comparison of zuora API definition in redoc (which has this functionality) and elements
Zuora definition: https://assets.zuora.com/zuora-documentation/swagger.yaml Zuora docs: https://www.zuora.com/developer/api-reference/#
Edited by Phil Sturgeon so we could get the work done. 👍.
Hey @savage-alex , I stumbled across the same issue and think the UX has gotten even more worse by now. In your shared screenshot with elements the API base URL section is in the right column.
Meanwhile the API Base URL, Security and Additional Information section will be always rendered first before the description starts. IMO it would make more sense to start with the description and move version, API base URL, Security and Additional Information into the right (3rd) column.
Additionally having the headings as mentioned in the left navigation would really great as well.
@savage-alex , were you able to solve the issue somehow meanwhile?
Hi, no I wasnt. I was mostly doing testing as we got an early access so was raising issues I saw. We are not using Elements yet