show the display name in the sidebar

demo/examples/petstore.yaml

@@ -61,6 +61,7 @@ tags:
     description: Everything about your Pets
   - name: store
     description: Access to Petstore orders
+    x-displayName: Petstore orders
   - name: user
     description: Operations about user
   - name: pet_model

packages/docusaurus-plugin-openapi/src/openapi/openapi.ts

@@ -23,7 +23,7 @@ import sdk, { Collection } from "postman-collection";
 
 import { ApiMetadata, ApiPageMetadata, InfoPageMetadata } from "../types";
 import { sampleFromSchema } from "./createExample";
-import { OpenApiObject, OpenApiObjectWithRef } from "./types";
+import { OpenApiObject, OpenApiObjectWithRef, TagObject } from "./types";
 
 /**
  * Finds any reference objects in the OpenAPI definition and resolves them to a finalized value.
@@ -151,6 +151,9 @@ function createItems(openapiData: OpenApiObject): ApiMetadata[] {
         frontMatter: {},
         api: {
           ...defaults,
+          tags: operationObject.tags?.map((tagName) =>
+            getTagDisplayName(tagName, openapiData.tags ?? [])
+          ),
           method,
           path,
           servers,
@@ -329,3 +332,25 @@ export async function processOpenapiFile(
 
   return items;
 }
+
+// order for picking items as a display name of tags
+const tagDisplayNameProperties = ["x-displayName", "name"] as const;
+
+function getTagDisplayName(tagName: string, tags: TagObject[]): string {
+  // find the very own tagObject
+  const tagObject = tags.find((tagObject) => tagObject.name === tagName) ?? {
+    // if none found, just fake one
+    name: tagName,
+  };
+
+  // return the first found and filled value from the property list
+  for (const property of tagDisplayNameProperties) {
+    const displayName = tagObject[property];
+    if (typeof displayName === "string") {
+      return displayName;
+    }
+  }
+
+  // always default to the tagName
+  return tagName;
+}

packages/docusaurus-plugin-openapi/src/openapi/types.ts

@@ -296,6 +296,7 @@ export interface TagObject {
   name: string;
   description?: string;
   externalDocs?: ExternalDocumentationObject;
+  "x-displayName"?: string;
 }
 
 export interface ReferenceObject {