Add support scaffolding for open api spec 3.2.

Author: wparad

.vscode/settings.json

@@ -12,7 +12,8 @@
         "randombytes",
         "rapidoc",
         "redoc",
-        "sublicensees"
+        "sublicensees",
+        "toposort"
     ],
     "files.exclude": {
     }

CHANGELOG.md

@@ -1,6 +1,9 @@
 # Changelog #
 This package follows standard semver, `<major>.<minor>.<build>`. No breaking changes will be introduced to existing `<minor>` versions.
 
+## 2.4
+* Add support for [OpenAPI Spec 3.2](https://www.openapis.org/blog/2025/09/23/announcing-openapi-v3-2).
+
 ## 2.3
 * Schema types will now utilize the title property for displaying, rather than the type ID, when defined.
 * Increase font sizes by 1px to set a more accessible default display.

README.md

@@ -45,7 +45,7 @@ This is an open source project managed by the [Authress Engineering team](https:
 ```
 
 ## Features
-- OpenAPI 3.X
+- OpenAPI 3.2+
 - Built in automatic Internationalization (I18n)
 - Works with any framework
 - View resources, models, and directly make API calls

package.json

@@ -118,6 +118,7 @@
     "sinon-chai": "^3.3.0",
     "style-loader": "^2.0.0",
     "terser-webpack-plugin": "^5.1.1",
+    "toposort": "^2.0.2",
     "webpack": "^5.30.0",
     "webpack-bundle-analyzer": "^4.4.0",
     "webpack-cli": "^4.6.0",

src/styles/font-styles.js

@@ -60,6 +60,7 @@ export default css`
   h1,h2,h3,h4,h5,h5{
     margin-block-end: 0.2em;
     margin-block-start: 0.5em;
+    padding-top: 0;
   }
   h3 {
     margin-top: 0;

src/templates/expanded-endpoint-template.js

@@ -14,11 +14,14 @@ export function expandedEndpointBodyTemplate(path, tag) {
   const nonEmptyApiKeys = this.resolvedSpec.securitySchemes.filter((v) => (v.finalKeyValue && path.security && path.security.some((ps) => ps[v.apiKeyId]))) || [];
 
   const codeSampleTabPanel = path.xCodeSamples ? codeSamplesTemplate.call(this, path.xCodeSamples) : '';
+
+  const tagSummary = tag?.summary ? html`<small style="font-weight: 400">- ${tag?.summary}</small>` : '';
   return html`
     ${this.renderStyle === 'read' ? html`<div class='divider' part="operation-divider"></div>` : ''}
     <div class='expanded-endpoint-body observe-me ${path.method}' part="section-operation ${path.elementId}" id='${path.elementId}'>
       ${(this.renderStyle === 'focused' && tag && tag.name !== 'General ⦂')
-        ? html`<div class="title tag-link" role="heading" aria-level="1" data-content-id="${tag.elementId}" @click="${(e) => this.scrollToEventTarget(e, false)}"> ${tag?.name} </div>`
+        ? html`<h1 style="display: inline; align-self: center" class="title tag-link" role="heading" aria-level="1" data-content-id="${tag.elementId}"
+          @click="${(e) => this.scrollToEventTarget(e, false)}"> ${tag?.name} ${tagSummary}</h1>`
         : ''}
       <slot name="${tag.elementId}"></slot>
 
@@ -91,9 +94,11 @@ export function expandedEndpointBodyTemplate(path, tag) {
 export function expandedTagTemplate(tagId, subsectionFullId) {
   const tag = (this.resolvedSpec.tags || []).find(t => t.elementId === tagId);
   const subsectionId = subsectionFullId.replace(`${tagId}--`, '');
+  const tagSummary = tag.summary ? html`<h2 style="font-weight: 400">${tag.summary}</h2>` : '';
   return html`
     <section id="${tag.elementId}" part="section-tag" class="regular-font section-gap--read-mode observe-me" style="">
-      <div class="title tag" part="label-tag-title" role="heading" aria-level="1">${tag.name}</div>
+      <h1 class="title tag" part="label-tag-title" role="heading" aria-level="1">${tag.name}</h1>
+      ${tagSummary}
       <slot name="${tag.elementId}--subsection--${subsectionId}">
         <div class="regular-font-size">
         ${

src/utils/spec-parser.js

@@ -3,6 +3,7 @@ import OpenApiResolver from 'openapi-resolver/dist/openapi-resolver.browser.js';
 import { marked } from 'marked';
 import { invalidCharsRegEx } from './common-utils.js';
 import cloneDeep from 'lodash.clonedeep';
+import toposort from 'toposort';
 
 export default async function ProcessSpec(specUrlOrObject, serverUrl = '') {
   const inputSpecIsAUrl = typeof specUrlOrObject === 'string' && specUrlOrObject.match(/^http/) || typeof specUrlOrObject === 'object' && typeof specUrlOrObject.href === 'string';
@@ -146,19 +147,27 @@ function getComponents(openApiSpec) {
 
 function groupByTags(openApiSpec) {
   const supportedMethods = ['get', 'query', 'put', 'post', 'patch', 'delete', 'head', 'options']; // this is also used for ordering endpoints by methods
-  const tags = openApiSpec.tags && Array.isArray(openApiSpec.tags)
-    ? openApiSpec.tags.map((t) => {
+  const rawTags = openApiSpec.tags && Array.isArray(openApiSpec.tags) ? openApiSpec.tags : [];
+  const unsortedTags = rawTags
+    // Only support nav tags in grouping, because these tags will be used for navigation.
+    .filter(t => !t.kind || t.kind === 'nav')
+    .map((t) => {
       const name = typeof t === 'string' ? t : t.name;
       return {
         elementId: `tag--${name.replace(invalidCharsRegEx, '-')}`,
         name: name,
+        summary: t.summary,
         description: t.description || '',
         headers: t.description ? getHeadersFromMarkdown(t.description) : [],
         paths: [],
         expanded: true
       };
-    })
-    : [];
+    });
+
+  const tagMap = unsortedTags.reduce((acc, t) => ({ ...acc, [t.name]: t }), {});
+
+  const tagDependencies = rawTags.map(t => t.parent && [t.parent, t.name] || [t.name, 'null']);
+  const tags = toposort(tagDependencies).map(tagName => tagMap[tagName]).filter(t => t);
 
   const pathsAndWebhooks = openApiSpec.paths || {};
   if (openApiSpec.webhooks) {

yarn.lock

@@ -7760,6 +7760,11 @@ [email protected]:
   resolved "https://registry.yarnpkg.com/toidentifier/-/toidentifier-1.0.1.tgz#3be34321a88a820ed1bd80dfaa33e479fbb8dd35"
   integrity sha512-o5sSPKEkg/DIQNmH43V0/uerLrpzVedkUh8tGNvaeXpfpuwjKenlSox/2O/BTlZUtEe+JG7s5YhEz608PlAHRA==
 
+toposort@^2.0.2:
+  version "2.0.2"
+  resolved "https://registry.yarnpkg.com/toposort/-/toposort-2.0.2.tgz#ae21768175d1559d48bef35420b2f4962f09c330"
+  integrity sha512-0a5EOkAUp8D4moMi2W8ZF8jcga7BgZd91O/yabJCFY8az+XSzeGyTKs0Aoo897iV1Nj6guFq8orWDS96z91oGg==
+
 totalist@^3.0.0:
   version "3.0.1"
   resolved "https://registry.yarnpkg.com/totalist/-/totalist-3.0.1.tgz#ba3a3d600c915b1a97872348f79c127475f6acf8"