docusaurus-plugin-openapi-docs 0.0.0-1007 → 0.0.0-1010

package/README.md

@@ -48,7 +48,7 @@ Key Features:
 
 ## Bootstrapping from Template (new Docusaurus site)
 
-Run the following to bootstrap a Docsaurus v3 site (classic theme) with `docusaurus-openapi-docs`:
+Run the following to bootstrap a Docusaurus v3 site (classic theme) with `docusaurus-openapi-docs`:
 
 ```bash
 npx create-docusaurus@3.7.0 my-website --package-manager yarn
@@ -192,12 +192,13 @@ The `docusaurus-plugin-openapi-docs` plugin can be configured with the following
 
 `versions` can be configured with the following options:
 
-| Name       | Type     | Default | Description                                                                                                              |
-| ---------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------ |
-| `specPath` | `string` | `null`  | Designated URL or path to the source of an OpenAPI specification file or directory of micro OpenAPI specification files. |
-| `ouputDir` | `string` | `null`  | Desired output path for versioned, generated MDX files.                                                                  |
-| `label`    | `string` | `null`  | _Optional:_ Version label used when generating version selector dropdown menu.                                           |
-| `baseUrl`  | `string` | `null`  | _Optional:_ Version base URL used when generating version selector dropdown menu.                                        |
+| Name          | Type     | Default | Description                                                                                                                |
+| ------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `specPath`    | `string` | `null`  | Designated URL or path to the source of an OpenAPI specification file or a directory of micro OpenAPI specification files. |
+| `outputDir`   | `string` | `null`  | Desired output path for versioned, generated MDX files.                                                                    |
+| `label`       | `string` | `null`  | _Optional:_ Version label used when generating the version selector dropdown menu.                                         |
+| `baseUrl`     | `string` | `null`  | _Optional:_ Version base URL used when generating the version selector dropdown menu.                                      |
+| `downloadUrl` | `string` | `null`  | _Optional:_ Designated URL for downloading the versioned OpenAPI specification.                                            |
 
 > All versions will automatically inherit `sidebarOptions` from the parent/base config.
 
@@ -329,11 +330,11 @@ yarn docusaurus gen-api-docs:version petstore:all
 
 > This will generate API docs for all of the OpenAPI specification (OAS) files referenced in your `versions` config and will also generate a `versions.json` file.
 
-> Substitue `all` with a specific version ID to generate/clean a specific version. Generating for `all` or a specific version ID will automatically update the `versions.json` file.
+> Substitute `all` with a specific version ID to generate or clean a specific version. Generating for `all` or a single version ID will automatically update the `versions.json` file.
 
 ## Developer Quick Start
 
-> Looking to make a contribution? Make sure to checkout out our contributing guide.
+> Looking to make a contribution? Make sure to check out our contributing guide.
 
 After [forking](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/fork) the main repository, run the following:
 

package/lib/openapi/openapi.js

@@ -211,6 +211,7 @@ function createItems(openapiData, options, sidebarOptions) {
                     jsonRequestBodyExample,
                     info: openapiData.info,
                 },
+                position: operationObject["x-position"],
             };
             items.push(apiPage);
         }
@@ -406,6 +407,21 @@ function createItems(openapiData, options, sidebarOptions) {
             items.push(tagPage);
         });
     }
+    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;
 }
 /**

package/lib/openapi/types.d.ts

@@ -128,6 +128,7 @@ export interface OperationObject {
     deprecated?: boolean;
     security?: SecurityRequirementObject[];
     servers?: ServerObject[];
+    "x-position"?: number;
     "x-deprecated-description"?: string;
 }
 export interface OperationObjectWithRef {

package/lib/openapi/utils/types.d.ts

@@ -76,6 +76,7 @@ export interface OpenAPIOperation {
     servers?: OpenAPIServer[];
     "x-codeSamples"?: OpenAPIXCodeSample[];
     "x-code-samples"?: OpenAPIXCodeSample[];
+    "x-position"?: number;
 }
 export interface OpenAPIParameter {
     name: string;

package/lib/types.d.ts

@@ -85,6 +85,7 @@ export interface ApiMetadataBase {
     frontMatter: Record<string, unknown>;
     method?: string;
     path?: string;
+    position?: number;
 }
 export interface ApiPageMetadata extends ApiMetadataBase {
     json?: string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docusaurus-plugin-openapi-docs",
   "description": "OpenAPI plugin for Docusaurus.",
-  "version": "0.0.0-1007",
+  "version": "0.0.0-1010",
   "license": "MIT",
   "keywords": [
     "openapi",
@@ -65,5 +65,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "864d5355b98d552679472455f533ef15313a0bee"
+  "gitHead": "5348bdfc01228df1025d380a949689f833dcfc13"
 }

package/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[];
 }
 

package/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;
 }
 

package/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 {

package/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 {