@xyd-js/openapi 0.1.0-build.168

package/__fixtures__/6.codeSamples/input.yaml

@@ -0,0 +1,75 @@
+openapi: 3.0.0
+info:
+  title: Sample API
+  description: Optional multiline or single-line description in [CommonMark](http://commonmark.org/help/) or HTML.
+  version: 0.1.9
+servers:
+  - url: http://api.example.com/v1
+    description: Optional server description, e.g. Main (production) server
+  - url: http://staging-api.example.com
+    description: Optional server description, e.g. Internal staging server for testing
+paths:
+  /users:
+    get:
+      summary: Returns a list of users
+      description: Optional extended description in CommonMark or HTML.
+      parameters:
+        - name: limit
+          in: query
+          description: Maximum number of items to return
+          required: true
+          schema:
+            type: integer
+            default: 20
+        - name: offset
+          in: query
+          description: Number of items to skip
+          required: false
+          schema:
+            type: integer
+            default: 0
+      responses:
+        '200':
+          description: A JSON array of users
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/User'
+      x-codeSamples:
+        - lang: bash
+          label: List all users
+          source: |
+            curl -X GET https://api.example.com/v1/users
+
+        - lang: javascript
+          label: List all users
+          source: |
+            const api = require('api-client');
+            api.users.list();
+components:
+  schemas:
+    User:
+      type: object
+      required:
+        - id
+        - username
+      properties:
+        id:
+          type: integer
+          format: int64
+        username:
+          type: string
+        email:
+          type: string
+          format: email
+        status:
+          type: string
+          enum: [active, inactive]
+        createdAt:
+          type: string
+          format: date-time
+        updatedAt:
+          type: string
+          format: date-time

package/__fixtures__/6.codeSamples/output.json

@@ -0,0 +1,293 @@
+[
+  {
+    "title": "Returns a list of users",
+    "canonical": "returns-a-list-of-users",
+    "description": "Optional extended description in CommonMark or HTML.",
+    "type": "rest_get",
+    "category": "rest",
+    "context": {
+      "method": "get",
+      "path": "/users",
+      "fullPath": "http:/api.example.com/v1/users",
+      "group": [
+        ""
+      ],
+      "scopes": []
+    },
+    "examples": {
+      "groups": [
+        {
+          "description": "Example request",
+          "examples": [
+            {
+              "codeblock": {
+                "tabs": [
+                  {
+                    "title": "bash",
+                    "language": "bash",
+                    "code": "curl -X GET https://api.example.com/v1/users\n"
+                  },
+                  {
+                    "title": "javascript",
+                    "language": "javascript",
+                    "code": "const api = require('api-client');\napi.users.list();\n"
+                  }
+                ]
+              }
+            }
+          ]
+        },
+        {
+          "description": "Example response",
+          "examples": [
+            {
+              "codeblock": {
+                "title": "200",
+                "tabs": [
+                  {
+                    "title": "application/json",
+                    "language": "json",
+                    "code": "[\n  {\n    \"id\": 0,\n    \"username\": \"string\",\n    \"email\": \"user@example.com\",\n    \"status\": \"active\",\n    \"createdAt\": \"2019-08-24T14:15:22Z\",\n    \"updatedAt\": \"2019-08-24T14:15:22Z\"\n  }\n]"
+                  }
+                ]
+              }
+            }
+          ]
+        }
+      ]
+    },
+    "definitions": [
+      {
+        "title": "Query parameters",
+        "properties": [
+          {
+            "name": "limit",
+            "type": "integer",
+            "description": "Maximum number of items to return",
+            "meta": [
+              {
+                "name": "defaults",
+                "value": 20
+              },
+              {
+                "name": "required",
+                "value": "true"
+              }
+            ]
+          },
+          {
+            "name": "offset",
+            "type": "integer",
+            "description": "Number of items to skip",
+            "meta": [
+              {
+                "name": "defaults",
+                "value": 0
+              }
+            ]
+          }
+        ]
+      },
+      {
+        "title": "Response",
+        "variants": [
+          {
+            "title": "200",
+            "description": "A JSON array of users",
+            "properties": [],
+            "rootProperty": {
+              "type": "$$array",
+              "properties": [
+                {
+                  "name": "id",
+                  "type": "integer",
+                  "description": "",
+                  "meta": [
+                    {
+                      "name": "required",
+                      "value": "true"
+                    }
+                  ]
+                },
+                {
+                  "name": "username",
+                  "type": "string",
+                  "description": "",
+                  "meta": [
+                    {
+                      "name": "required",
+                      "value": "true"
+                    }
+                  ]
+                },
+                {
+                  "name": "email",
+                  "type": "string",
+                  "description": "",
+                  "meta": []
+                },
+                {
+                  "name": "status",
+                  "type": "$$enum",
+                  "description": "",
+                  "meta": [
+                    {
+                      "name": "enum-type",
+                      "value": "string"
+                    }
+                  ],
+                  "properties": [
+                    {
+                      "name": "active",
+                      "type": "string",
+                      "description": "",
+                      "meta": []
+                    },
+                    {
+                      "name": "inactive",
+                      "type": "string",
+                      "description": "",
+                      "meta": []
+                    }
+                  ]
+                },
+                {
+                  "name": "createdAt",
+                  "type": "string",
+                  "description": "",
+                  "meta": []
+                },
+                {
+                  "name": "updatedAt",
+                  "type": "string",
+                  "description": "",
+                  "meta": []
+                }
+              ]
+            },
+            "meta": [
+              {
+                "name": "status",
+                "value": "200"
+              },
+              {
+                "name": "contentType",
+                "value": "application/json"
+              },
+              {
+                "name": "definitionDescription",
+                "value": ""
+              }
+            ]
+          }
+        ],
+        "properties": []
+      }
+    ]
+  },
+  {
+    "title": "User",
+    "description": "",
+    "canonical": "objects/User",
+    "definitions": [
+      {
+        "title": "User",
+        "properties": [
+          {
+            "name": "id",
+            "type": "integer",
+            "description": "",
+            "meta": [
+              {
+                "name": "required",
+                "value": "true"
+              }
+            ]
+          },
+          {
+            "name": "username",
+            "type": "string",
+            "description": "",
+            "meta": [
+              {
+                "name": "required",
+                "value": "true"
+              }
+            ]
+          },
+          {
+            "name": "email",
+            "type": "string",
+            "description": "",
+            "meta": []
+          },
+          {
+            "name": "status",
+            "type": "$$enum",
+            "description": "",
+            "meta": [
+              {
+                "name": "enum-type",
+                "value": "string"
+              }
+            ],
+            "properties": [
+              {
+                "name": "active",
+                "type": "string",
+                "description": "",
+                "meta": []
+              },
+              {
+                "name": "inactive",
+                "type": "string",
+                "description": "",
+                "meta": []
+              }
+            ]
+          },
+          {
+            "name": "createdAt",
+            "type": "string",
+            "description": "",
+            "meta": []
+          },
+          {
+            "name": "updatedAt",
+            "type": "string",
+            "description": "",
+            "meta": []
+          }
+        ],
+        "meta": []
+      }
+    ],
+    "examples": {
+      "groups": [
+        {
+          "description": "Example",
+          "examples": [
+            {
+              "codeblock": {
+                "tabs": [
+                  {
+                    "title": "json",
+                    "language": "json",
+                    "code": "{\n  \"id\": 0,\n  \"username\": \"\",\n  \"email\": \"\",\n  \"status\": \"\",\n  \"createdAt\": \"\",\n  \"updatedAt\": \"\"\n}"
+                  }
+                ]
+              }
+            }
+          ]
+        }
+      ]
+    },
+    "type": "rest_component_schema",
+    "context": {
+      "componentSchema": "User",
+      "group": [
+        "Objects"
+      ]
+    }
+  }
+]

package/__tests__/oapSchemaToReferences.test.ts

@@ -0,0 +1,82 @@
+import {describe, expect, it} from 'vitest'
+
+import {testOasSchemaToReferences} from "./utils";
+import {uniformOasOptions} from "../src/types";
+import {uniformOpenAIMeta} from "../__fixtures__/-2.complex.openai/pluginOasOpenai";
+import {uniformPluginXDocsSidebar} from "../src/xdocs/pluginSidebar";
+
+const tests: {
+    name: string;
+    description: string,
+    url?: string, // URL to the OpenAPI schema
+    plugins?: any[]; // TODO: fix any,
+    options?: uniformOasOptions
+}[] = [
+    {
+        name: "-3.random",
+        // url: "https://raw.githubusercontent.com/bump-sh-examples/train-travel-api/main/openapi.yaml",
+        // url: "https://raw.githubusercontent.com/digitalocean/openapi/main/specification/DigitalOcean-public.v2.yaml",
+        // url: "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/ghes-3.0/ghes-3.0.json",
+        // url: "https://raw.githubusercontent.com/box/box-openapi/main/openapi.json",
+        // url: "https://api.apis.guru/v2/specs/nytimes.com/article_search/1.0.0/openapi.yaml",
+        // url: "https://developers.intercom.com/_spec/docs/references/@2.11/rest-api/api.intercom.io.json",
+        // url: "https://raw.githubusercontent.com/livesession/livesession-openapi/refs/heads/master/openapi.yaml",
+        // url: "https://openapi.vercel.sh",
+        description: "",
+        // plugins: [
+        //     uniformPluginXDocsSidebar
+        // ]
+    },
+
+    // {
+    //     name: "1.basic",
+    //     description: "Basic OpenAPI API example",
+    // },
+    // {
+    //     name: "2.more",
+    //     description: "More OpenAPI API example",
+    // },
+    // {
+    //     name: "3.multiple-responses",
+    //     description: "Multiple responses OpenAPI API example",
+    // },
+    // {
+    //     name: "5.xdocs.codeLanguages",
+    //     description: "x-docs OpenAPI API codeLanguages example",
+    // },
+    // {
+    //     name: "5.xdocs.sidebar",
+    //     description: "x-docs OpenAPI API sidebar example",
+    //     plugins: [
+    //         uniformPluginXDocsSidebar
+    //     ]
+    // },
+    // {
+    //     name: "6.codeSamples",
+    //     description: "x-codeSamples OpenAPI API example",
+    // },
+]
+
+describe("oapSchemaToReferences", {timeout: 15000}, () => {
+    tests.forEach((test) => {
+        it(`[${test.name}]: ${test.description}`, async () => {
+            await testOasSchemaToReferences(test.name, test.options, test.plugins, test.url);
+        });
+    });
+});
+
+
+// TODO: uncomment when ready
+// {
+//     name: "-2.complex.openai",
+//     description: "OpenAI OpenAPI API example",
+//     plugins: [
+//         uniformOpenAIMeta,
+//     ],
+//     // options: {
+//     //    regions: [
+//     //        // "/components/schemas/ListAssistantsResponse",
+//     //        "POST /responses"
+//     //    ]
+//     // }
+// },

package/__tests__/utils.ts

@@ -0,0 +1,81 @@
+import path from "node:path";
+import fs from "node:fs";
+
+import {expect} from "vitest";
+
+import uniform from "@xyd-js/uniform";
+
+import {
+    deferencedOpenAPI,
+    oapSchemaToReferences,
+
+    type uniformOasOptions
+} from "../index";
+
+// Helper function to remove functions from an object
+function removeFunctions(obj: any): any {
+    if (typeof obj !== 'object' || obj === null) {
+        return obj;
+    }
+    
+    if (Array.isArray(obj)) {
+        return obj.map(removeFunctions);
+    }
+    
+    const result: any = {};
+    for (const key in obj) {
+        if (typeof obj[key] !== 'function') {
+            result[key] = removeFunctions(obj[key]);
+        }
+    }
+    return result;
+}
+
+// Helper function to run a test with a specific fixture
+export async function testOasSchemaToReferences(
+    fixtureName: string,
+    options?: uniformOasOptions,
+    plugins?: any[], // TODO: fix any,
+    url?: string // URL to the OpenAPI schema
+) {
+    const schemaLocation = url ? url : fullFixturePath(`${fixtureName}/input.yaml`)
+
+    const schemalocation = await deferencedOpenAPI(schemaLocation);
+    let result = oapSchemaToReferences(schemalocation, options);
+    if (plugins?.length) {
+        const uni = uniform(result, {
+            plugins
+        })
+
+        result = uni.references;
+    }
+
+    // saveResultAsOutput(fixtureName, result) // TODO: comment for prod
+
+    const expectedOutput = readFixtureOutput(`${fixtureName}/output.json`);
+    try {
+        // Remove functions before comparison
+        const cleanResult = removeFunctions(result);
+        const cleanExpected = removeFunctions(expectedOutput);
+        expect(cleanResult).toEqual(cleanExpected);
+    } catch (error) {
+        if (result?.length > 100) {
+            throw new Error(`FAILED: The diff result is too long (${result.length} items) to show.`);
+        }
+        throw error;
+    }
+}
+
+// Helper function to read fixture output
+function readFixtureOutput(name: string) {
+    const fixturePath = fullFixturePath(name);
+    return JSON.parse(fs.readFileSync(fixturePath, "utf8"));
+}
+
+function fullFixturePath(name: string) {
+    return path.join(__dirname, "../__fixtures__", name);
+}
+
+function saveResultAsOutput(fixtureName: string, result: any) {
+    fs.writeFileSync(fullFixturePath(fixtureName + "/output.json"), JSON.stringify(result, null, 2));
+}