@xyd-js/openapi 0.1.0-xyd.6 → 0.1.0-xyd.64

package/src/utils.ts

@@ -1,28 +1,108 @@
 import path from "path";
-import fs from "fs";
+import fs from "fs/promises";
+
 import yaml from "js-yaml";
-import $refParser from "json-schema-ref-parser";
-import {OpenAPIV3} from "openapi-types";
+import { OpenAPIV3 } from "openapi-types";
+import GithubSlugger from 'github-slugger';
+import $refParser, { ParserOptions } from "@apidevtools/json-schema-ref-parser";
+
+import { ReferenceType } from "@xyd-js/uniform";
+
+export function slug(str: string): string {
+    const slugger = new GithubSlugger();
+    return slugger.slug(str);
+}
+
+// deferencedOpenAPI reads an OpenAPI spec file and returns a dereferenced OpenAPIV3.Document
+// dereferenced means that all $ref references are resolved automatically
+export async function deferencedOpenAPI(openApiPath: string) {
+    const openApiSpec = await readOpenApiSpec(openApiPath);
+    if (!openApiSpec) {
+        return
+    }
+
+    const cwd = process.cwd();
+
+    const remoteOasPath = openApiPath.startsWith('http://') || openApiPath.startsWith('https://') ? true : false
+
+    const options: ParserOptions = {
+        dereference: {
+            onDereference(path: any, value: any, parent: any) {
+                if (value && typeof value === 'object') {
+                    value.__UNSAFE_refPath = () => path
+                }
+                if (parent && typeof parent === 'object') {
+                    parent.__UNSAFE_refPath = () => path
+                }
+            }
+        }
+    } as ParserOptions;
 
-import {ReferenceType} from "@xyd-js/uniform";
+    if (remoteOasPath) {
+        if (!options.resolve) {
+            options.resolve = {}
+        }
 
-type Parameters = {
-    query?: Record<string, string | number | boolean>;
-    headers?: Record<string, string>;
-};
+        options.resolve.file = {
+            read: async (file: any) => {
+                // 1) Convert absolute local path back into a repo-relative path:
+                //    "/Users/.../docs/foo.md" → "docs/foo.md"
+                let rel = path.relative(cwd, file.url);
+                rel = rel.split(path.sep).join('/');
+
+                // 2) Resolve against your GitHub raw URL:
+                const absoluteUrl = new URL(rel, openApiPath).href;
+                //    → "https://raw.githubusercontent.com/.../docs/foo.md"
+
+                // 3) Fetch it:
+                const res = await fetch(absoluteUrl);
+                if (!res.ok) {
+                    throw new Error(`Failed to fetch ${absoluteUrl}: ${res.status}`);
+                }
+
+                let content;
+                if (file.extension === '.json' || file.extension === '.yaml' || file.extension === '.yml') {
+                    // If the file is JSON or YAML, return the parsed content
+                    if (file.extension === '.json') {
+                        content = await res.json();
+                    } else {
+                        content = yaml.load(await res.text());
+                    }
+                } else {
+                    content = await res.text();        // hand back the Markdown
+                }
+
+                return content;
+            }
+        }
+    }
 
-export function toPascalCase(str: string): string {
-    return str
-        .split(/[\s_-]+/)
-        .map(word => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
-        .join('');
+    await $refParser.dereference(openApiSpec, options);
+
+    return openApiSpec as OpenAPIV3.Document
 }
 
-// readOpenApiSpec reads an OpenAPI spec file and returns the content
-function readOpenApiSpec(filePath: string) {
-    const ext = path.extname(filePath).toLowerCase();
-    const content = fs.readFileSync(filePath, 'utf-8');
+// readOpenApiSpec reads an OpenAPI spec file or URL and returns the content
+async function readOpenApiSpec(filePath: string) {
+    let content: string;
 
+    if (filePath.startsWith('http://') || filePath.startsWith('https://')) {
+        const response = await fetch(filePath);
+        if (!response.ok) {
+            throw new Error(`Failed to fetch OpenAPI spec from URL: ${response.statusText}`);
+        }
+        content = await response.text();
+    } else {
+        try {
+            await fs.access(filePath);
+        } catch (error) {
+            console.log(`⚠️ "${filePath}" is defined in the docs.json navigation but the file does not exist.`)
+            return
+        }
+        content = await fs.readFile(filePath, 'utf-8');
+    }
+
+    const ext = path.extname(filePath).toLowerCase();
     if (ext === '.yaml' || ext === '.yml') {
         return yaml.load(content);
     } else if (ext === '.json') {
@@ -32,17 +112,6 @@ function readOpenApiSpec(filePath: string) {
     }
 }
 
-// deferencedOpenAPI reads an OpenAPI spec file and returns a dereferenced OpenAPIV3.Document
-// dereferenced means that all $ref references are resolved automatically
-export async function deferencedOpenAPI(openApiPath: string) {
-    const openApiSpec = readOpenApiSpec(openApiPath);
-
-    //@ts-ignore TODO: fix ts
-    await $refParser.dereference(openApiSpec);
-
-    return openApiSpec as OpenAPIV3.Document
-}
-
 // httpMethodToUniformMethod converts an HTTP method to a uniform ReferenceType
 export function httpMethodToUniformMethod(method: string): ReferenceType | null {
     switch (method) {
@@ -56,69 +125,14 @@ export function httpMethodToUniformMethod(method: string): ReferenceType | null
             return ReferenceType.REST_HTTP_POST
         case 'delete':
             return ReferenceType.REST_HTTP_DELETE
-        // case 'options':
-        //     return ReferenceType.REST_HTTP_OPTIONS
-        // case 'head':
-        //     return ReferenceType.REST_HTTP_HEAD
-        // case 'trace':
-        //     return ReferenceType.REST_HTTP_TRACE
+        case 'options':
+            return ReferenceType.REST_HTTP_OPTIONS
+        case 'head':
+            return ReferenceType.REST_HTTP_HEAD
+        case 'trace':
+            return ReferenceType.REST_HTTP_TRACE
         default:
             return null
     }
 }
 
-// schemaToRequestBody generates a request body from an OpenAPI schema
-function schemaToRequestBody(schema: OpenAPIV3.SchemaObject): string {
-    const requestBody: any = {};
-
-    if (schema.type === 'object' && schema.properties) {
-        for (const [key, value] of Object.entries(schema.properties)) {
-            if ((value as OpenAPIV3.SchemaObject).default !== undefined) {
-                requestBody[key] = (value as OpenAPIV3.SchemaObject).default;
-            } else {
-                requestBody[key] = null; // or some placeholder value
-            }
-        }
-    }
-
-    return JSON.stringify(requestBody);
-}
-
-// generateRequestInitFromOpenAPIObject generates a RequestInit object from an OpenAPI object
-export function generateRequestInitFromOapOperation(
-    urlPath: string,
-    operation: OpenAPIV3.OperationObject
-): { url: string, reqInit: RequestInit } {
-    const reqInit: RequestInit = {}
-    let queryParams = '';
-
-    if (operation.parameters) {
-        const parameters = operation.parameters as OpenAPIV3.ParameterObject[]
-
-        const params = new URLSearchParams(
-            Object.entries(parameters).map(([key, value]) => [key, String(value)])
-        ).toString();
-
-        queryParams += `?${params}`;
-    }
-
-    if (operation.requestBody) {
-        const reqBody = operation.requestBody as OpenAPIV3.RequestBodyObject;
-        const contentType = Object.keys(reqBody.content || {})[0];
-
-        if (contentType === "application/json") {
-            const schema = reqBody.content['application/json'].schema as OpenAPIV3.SchemaObject
-
-            reqInit.body = schemaToRequestBody(schema);
-            reqInit.headers = {
-                'Content-Type': 'application/json',
-            }
-        }
-    }
-
-    return {
-        url: `${urlPath}${queryParams}`,
-        reqInit,
-    };
-}
-

package/src/xdocs/index.ts

@@ -0,0 +1,18 @@
+import {OpenAPIV3} from "openapi-types";
+import {XDocs} from "./types";
+
+export function xDocsLanguages(oasDoc: OpenAPIV3.Document): string[] | null {
+    const xDocs = getXDocs(oasDoc);
+    if (!xDocs) {
+        return null
+    }
+
+    return xDocs?.codeLanguages ?? null
+}
+
+export function getXDocs(oasDoc: OpenAPIV3.Document): XDocs | null {
+    if (!("x-docs" in oasDoc)) {
+        return null
+    }
+    return oasDoc["x-docs"] as XDocs | null
+}