From 89692a8ade4d5038146fd9ae35e0e5f988237dbe Mon Sep 17 00:00:00 2001
From: Bryan <blindaa121@gmail.com>
Date: Tue, 10 Jun 2025 17:38:26 -0700
Subject: [PATCH 1/2] Add support for x-position vendor extension and sorting
 logic

---
 .../src/openapi/openapi.ts                      | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/packages/docusaurus-plugin-openapi-docs/src/openapi/openapi.ts b/packages/docusaurus-plugin-openapi-docs/src/openapi/openapi.ts
index 64d7f23e1..675c0a83f 100644
--- a/packages/docusaurus-plugin-openapi-docs/src/openapi/openapi.ts
+++ b/packages/docusaurus-plugin-openapi-docs/src/openapi/openapi.ts
@@ -263,6 +263,7 @@ function createItems(
           jsonRequestBodyExample,
           info: openapiData.info,
         },
+        position: operationObject["x-position"] as number | undefined,
       };
 
       items.push(apiPage);
@@ -509,6 +510,22 @@ function createItems(
       });
   }
 
+  items.sort((a, b) => {
+    // Items with position come first, sorted by position
+    if (a.position !== undefined && b.position !== undefined) {
+      return a.position - b.position;
+    }
+    // Items with position come before items without position
+    if (a.position !== undefined) {
+      return -1;
+    }
+    if (b.position !== undefined) {
+      return 1;
+    }
+    // If neither has position, maintain original order
+    return 0;
+  });
+
   return items as ApiMetadata[];
 }
 

From 91aaf760c419e0bb18ac54493469573d5db6e2c0 Mon Sep 17 00:00:00 2001
From: Bryan <blindaa121@gmail.com>
Date: Tue, 10 Jun 2025 17:39:17 -0700
Subject: [PATCH 2/2] Add position and x-position types

---
 packages/docusaurus-plugin-openapi-docs/src/openapi/types.ts    | 2 +-
 .../docusaurus-plugin-openapi-docs/src/openapi/utils/types.ts   | 1 +
 packages/docusaurus-plugin-openapi-docs/src/types.ts            | 1 +
 3 files changed, 3 insertions(+), 1 deletion(-)

diff --git a/packages/docusaurus-plugin-openapi-docs/src/openapi/types.ts b/packages/docusaurus-plugin-openapi-docs/src/openapi/types.ts
index 317f3cfc2..b5db1a249 100644
--- a/packages/docusaurus-plugin-openapi-docs/src/openapi/types.ts
+++ b/packages/docusaurus-plugin-openapi-docs/src/openapi/types.ts
@@ -156,8 +156,8 @@ export interface OperationObject {
   deprecated?: boolean;
   security?: SecurityRequirementObject[];
   servers?: ServerObject[];
-
   // extensions
+  "x-position"?: number;
   "x-deprecated-description"?: string;
 }
 
diff --git a/packages/docusaurus-plugin-openapi-docs/src/openapi/utils/types.ts b/packages/docusaurus-plugin-openapi-docs/src/openapi/utils/types.ts
index cdfb3121c..e46e86483 100644
--- a/packages/docusaurus-plugin-openapi-docs/src/openapi/utils/types.ts
+++ b/packages/docusaurus-plugin-openapi-docs/src/openapi/utils/types.ts
@@ -89,6 +89,7 @@ export interface OpenAPIOperation {
   servers?: OpenAPIServer[];
   "x-codeSamples"?: OpenAPIXCodeSample[];
   "x-code-samples"?: OpenAPIXCodeSample[]; // deprecated
+  "x-position"?: number;
 }
 
 export interface OpenAPIParameter {
diff --git a/packages/docusaurus-plugin-openapi-docs/src/types.ts b/packages/docusaurus-plugin-openapi-docs/src/types.ts
index 721aea14d..664728f99 100644
--- a/packages/docusaurus-plugin-openapi-docs/src/types.ts
+++ b/packages/docusaurus-plugin-openapi-docs/src/types.ts
@@ -118,6 +118,7 @@ export interface ApiMetadataBase {
   frontMatter: Record<string, unknown>;
   method?: string;
   path?: string;
+  position?: number;
 }
 
 export interface ApiPageMetadata extends ApiMetadataBase {