@xyd-js/openapi 0.1.0-xyd.11 → 0.1.0-xyd.13

package/src/converters/oas-componentSchemas.ts

@@ -0,0 +1,205 @@
+import {OpenAPIV3} from "openapi-types";
+
+import {
+    Reference,
+    Definition,
+    DefinitionProperty,
+    ReferenceType,
+    OpenAPIReferenceContext, SymbolDef,
+    ExampleGroup,
+    CodeBlockTab,
+} from "@xyd-js/uniform";
+
+import {OasJSONSchema, uniformOasOptions} from "../types";
+import {schemaObjectToUniformDefinitionProperties} from "../oas-core";
+
+export function schemaComponentsToUniformReferences(
+    openapi: OpenAPIV3.Document,
+    options?: uniformOasOptions,
+): Reference[] {
+    const references: Reference[] = [];
+
+    if (!openapi.components?.schemas) {
+        return references;
+    }
+
+    for (const [componentSchemaName, componentSchema] of Object.entries(openapi.components.schemas)) {
+        if (options?.regions && options.regions.length > 0) {
+            if (!options.regions.some(region => region === "/components/schemas/" + componentSchemaName)) {
+                continue
+            }
+        }
+
+        if ('$ref' in componentSchema) {
+            console.warn(`Skipping reference object: ${componentSchemaName}`);
+            continue; // Skip reference objects
+        }
+
+        let properties: DefinitionProperty[] = [];
+        let rootProperty: DefinitionProperty | undefined = undefined;
+        const respProperties = schemaObjectToUniformDefinitionProperties(componentSchema, false) || [];
+        if (Array.isArray(respProperties)) {
+            properties = respProperties
+        } else {
+            rootProperty = respProperties
+        }
+
+        const symbolDef = definitionPropertyTypeDef(componentSchema)
+
+        const definition: Definition = {
+            title: componentSchemaName,
+            properties,
+            rootProperty,
+            meta: [],
+            symbolDef,
+        };
+
+        // Create reference
+        const reference: Reference = {
+            title: componentSchemaName,
+            description: componentSchema.description || "",
+            canonical: `objects/${componentSchemaName}`,
+            definitions: [definition],
+            examples: {
+                groups: createSchemaExampleGroup(componentSchema as OpenAPIV3.SchemaObject)
+            },
+            type: ReferenceType.REST_COMPONENT_SCHEMA,
+            context: {
+                componentSchema: componentSchemaName,
+                group: ["Objects"]
+            } as OpenAPIReferenceContext
+        };
+
+        // TODO: !!!! better api !!!!
+        reference.__UNSAFE_selector = function __UNSAFE_selector(selector: string) {
+            switch (selector) {
+                case "[schema]": {
+                    return openapi
+                }
+
+                case "[component]": {
+                    return componentSchema
+                }
+
+                default:
+                    return null
+            }
+        }
+
+        references.push(reference);
+    }
+
+    return references;
+}
+
+function createSchemaExampleGroup(schema: OpenAPIV3.SchemaObject, map: any): ExampleGroup[] {
+    const example = generateSchemaExample(schema);
+    if (!example) {
+        return [];
+    }
+
+    const tabs: CodeBlockTab[] = [{
+        title: 'json',
+        language: 'json',
+        code: JSON.stringify(example, null, 2)
+    }];
+
+    return [{
+        description: 'Example',
+        examples: [{
+            codeblock: {
+                tabs
+            }
+        }]
+    }];
+}
+
+function definitionPropertyTypeDef(
+    schema: OpenAPIV3.SchemaObject | undefined,
+) {
+    if (!schema) {
+        return
+    }
+
+    let typeDef: SymbolDef | undefined
+    let oasSchema = schema as OasJSONSchema
+    if (oasSchema.type === "array") {
+        oasSchema = oasSchema.items as OasJSONSchema
+    }
+    if (oasSchema?.__internal_getRefPath) {
+        const symbolId = oasSchema.__internal_getRefPath()
+
+        typeDef = {
+            id: symbolId,
+        }
+    }
+
+    return typeDef
+}
+
+function generateSchemaExample(
+    schema: OpenAPIV3.SchemaObject,
+    visitedExample?: Map<OpenAPIV3.SchemaObject, any>,
+    parent?: any
+): any {
+    if (!schema) {
+        return null;
+    }
+    if (!visitedExample) {
+        visitedExample = new Map<OpenAPIV3.SchemaObject, any>();
+    }
+
+    const cached = visitedExample.get(schema)
+    if (cached) {
+        return JSON.parse(JSON.stringify(cached)); // Return a deep copy of the cached example
+    }
+    if (parent) {
+        visitedExample.set(schema, parent);
+    }
+
+    // Handle examples array
+    if ('examples' in schema && Array.isArray(schema.examples)) {
+        const v =  schema.examples[0];
+        visitedExample.set(schema, v);
+        return v; // Return the first example from the examples array
+    }
+
+    // Handle single example
+    if ('example' in schema && schema.example !== undefined) {
+        const v =  schema.example;
+        visitedExample.set(schema, v);
+        return v; // Return the single example if it exists
+    }
+
+    // Handle object type with properties
+    if (schema.type === 'object' && schema.properties) {
+        const result: Record<string, any> = {};
+        for (const [propName, propSchema] of Object.entries(schema.properties)) {
+            result[propName] = generateSchemaExample(propSchema as OpenAPIV3.SchemaObject, visitedExample, result);
+        }
+        visitedExample.set(schema, result);
+        return result;
+    }
+
+    // Handle array type
+    if (schema.type === 'array' && schema.items) {
+        const itemExample = generateSchemaExample(schema.items as OpenAPIV3.SchemaObject, visitedExample);
+        const v = itemExample ? [itemExample] : [];
+        visitedExample.set(schema, v);
+
+        return v; // Return an array with a single item example
+    }
+
+    // Handle primitive types with default values
+    switch (schema.type) {
+        case 'string':
+            return '';
+        case 'number':
+        case 'integer':
+            return 0;
+        case 'boolean':
+            return false;
+        default:
+            return null;
+    }
+}

package/src/converters/oas-examples.ts

@@ -0,0 +1,417 @@
+import {OpenAPIV3} from "openapi-types";
+import Oas from "oas";
+// @ts-ignore
+import {Operation} from 'oas/operation'; // TODO: fix ts
+import oasToSnippet from "@readme/oas-to-snippet";
+import OpenAPISampler from "openapi-sampler";
+import type {JSONSchema7} from "json-schema";
+
+import {ExampleGroup, Example, CodeBlockTab} from "@xyd-js/uniform";
+
+import {BUILT_IN_PROPERTIES} from "../const";
+import {xDocsLanguages} from "../xdocs";
+
+// TODO: custom snippet languages options
+const DEFAULT_CODE_LANGUAGES = ["shell", "javascript", "python", "go"]
+
+// TODO: option with another languages
+export function oapExamples(
+    oas: Oas,
+    operation: Operation,
+    visitedExamples?: Map<JSONSchema7 | JSONSchema7[], any>
+): ExampleGroup[] {
+    const exampleGroups = [
+        ...reqExamples(operation, oas, visitedExamples),
+        ...resBodyExmaples(operation, oas, visitedExamples),
+    ]
+
+    return exampleGroups
+}
+
+function langFallback(lang: string): string {
+    const langLower = lang.toLowerCase()
+
+    switch (langLower) {
+        case "curl": {
+            return "shell";
+        }
+    }
+
+    return langLower;
+}
+
+function smartDeepCopy<T>(obj: T, excludeProps: string[] = []): T {
+    const seen = new WeakMap();
+    
+    function copy(value: any): any {
+        // Handle primitives and null
+        if (value === null || typeof value !== 'object') {
+            return value;
+        }
+
+        // Handle arrays
+        if (Array.isArray(value)) {
+            return value.map(copy);
+        }
+
+        // Handle dates
+        if (value instanceof Date) {
+            return new Date(value);
+        }
+
+        // Check for circular references
+        if (seen.has(value)) {
+            return seen.get(value);
+        }
+
+        // Create new object
+        const result: any = {};
+        seen.set(value, result);
+
+        // Copy all properties except excluded ones
+        for (const [key, val] of Object.entries(value)) {
+            const propPath = key;
+            if (!excludeProps.some(prop => propPath.startsWith(prop))) {
+                result[key] = copy(val);
+            }
+        }
+
+        return result;
+    }
+
+    return copy(obj);
+}
+
+function excludeProperties(operation: Operation, excludeProps: string[]): Operation {
+    return smartDeepCopy(operation, excludeProps);
+}
+
+function reqExamples(operation: Operation, oas: Oas, vistedExamples?: Map<JSONSchema7 | JSONSchema7[], any>): ExampleGroup[] {
+    const exampleGroups: ExampleGroup[] = []
+    const examples: Example[] = []
+    const tabs: CodeBlockTab[] = []
+
+    // Handle x-codeSamples if present
+    if (operation.schema['x-codeSamples']) {
+        const codeSamples = operation.schema['x-codeSamples'] as Array<{ lang: string; source: string }>
+        const codeSampleTabs: CodeBlockTab[] = codeSamples.map(sample => ({
+            title: sample.lang,
+            language: langFallback(sample.lang),
+            code: sample.source
+        }))
+
+        if (codeSampleTabs.length > 0) {
+            examples.push({
+                codeblock: {
+                    tabs: codeSampleTabs
+                }
+            })
+
+            exampleGroups.push({
+                description: "Example request",
+                examples
+            })
+
+            return exampleGroups
+        }
+    }
+
+    // Create a single object with all parameters grouped by their location
+    const paramData = operation.schema.parameters
+        ? (operation.schema.parameters as OpenAPIV3.ParameterObject[]).reduce((acc, param) => {
+            const location = param.in || 'query'
+            if (!acc[location]) {
+                acc[location] = {}
+            }
+
+            let value = param.example
+            if (!value && param.schema) {
+                value = OpenAPISampler.sample(sanitizeSchema(param.schema as JSONSchema7))
+            }
+            if (value !== undefined) {
+                acc[location][param.name] = value
+            }
+            return acc
+        }, {} as Record<string, Record<string, any>>)
+        : {}
+
+    // Get request body data if it exists
+    let bodyData = {}
+    if (operation.schema.requestBody) {
+        const body = operation.schema.requestBody as OpenAPIV3.RequestBodyObject
+        const contentTypes = Object.keys(body.content)
+
+        if (contentTypes.length > 0) {
+            const contentType = contentTypes[contentTypes.length - 1]
+            const content = body.content[contentType]
+            let schema = content?.schema as JSONSchema7
+
+            if (schema) {
+                schema = fixAllOfBug(schema)
+                schema = sanitizeSchema(schema)
+
+                let requestData
+                if (content.examples) {
+                    const requestExample = content.examples["request"]
+                    if (requestExample && "value" in requestExample) {
+                        requestData = requestExample.value
+                    }
+                }
+
+                if (!requestData) {
+                    requestData = OpenAPISampler.sample(schema)
+                }
+
+                if (contentType === 'application/x-www-form-urlencoded') {
+                    bodyData = {formData: requestData}
+                } else {
+                    bodyData = {body: requestData}
+                }
+            }
+        }
+    }
+
+    // Check if we have parameters or request body
+    const hasRequestBody = operation.schema.requestBody !== undefined
+    const hasParameters = Object.keys(paramData).length > 0
+
+    // Generate examples if we have either parameters or request body, or if we have neither
+    if (hasParameters || hasRequestBody || (!hasRequestBody && !hasParameters)) {
+        const langs = xDocsLanguages(operation.api) || DEFAULT_CODE_LANGUAGES
+        langs.forEach(lang => {
+            // TODO: needed for circural references - find better solution?
+            const operationCopy = excludeProperties(operation, ['api.components', 'api.paths']);
+            const {code} = oasToSnippet(oas, operationCopy, {
+                ...paramData,
+                ...bodyData
+            }, null, lang)
+
+            tabs.push({
+                title: lang,
+                language: lang,
+                code: code || ""
+            })
+        })
+
+        if (tabs.length > 0) {
+            examples.push({
+                codeblock: {
+                    tabs
+                }
+            })
+        }
+
+        if (examples.length > 0) {
+            exampleGroups.push({
+                description: "Example request",
+                examples
+            })
+        }
+    }
+
+    return exampleGroups
+}
+
+function resBodyExmaples(operation: Operation, oas: Oas, vistedExamples?: Map<JSONSchema7 | JSONSchema7[], any>): ExampleGroup[] {
+    const exampleGroups: ExampleGroup[] = []
+
+    if (operation.schema.responses) {
+        const responses = operation.schema.responses as OpenAPIV3.ResponsesObject
+
+        const examples: Example[] = []
+
+        Object.entries(responses).forEach(([status, r]) => {
+            const response = r as OpenAPIV3.ResponseObject
+            if (!response.content) {
+                return
+            }
+
+            const contentTypes = Object.keys(response.content)
+            if (contentTypes.length === 0) {
+                return
+            }
+
+            const tabs: CodeBlockTab[] = []
+
+            for (const contentType of contentTypes) {
+                const content = response.content[contentType]
+                const schema = content?.schema as JSONSchema7
+
+                if (!schema) {
+                    continue
+                }
+
+                let responseData
+                // Check for examples in the response content
+                if (content.examples) {
+                    const responseExample = content.examples["response"]
+                    if (responseExample && "value" in responseExample) {
+                        responseData = responseExample.value
+                    } else {
+                        const namedExamples: Example[] = []
+                        const exampleNames = Object.keys(content.examples)
+
+                        exampleNames.forEach((exampleName) => {
+                            const data = content?.examples?.[exampleName]
+
+                            if (!data || !("value" in data) || typeof data.value != "object") {
+                                return
+                            }
+
+                            namedExamples.push({
+                                description: "",
+                                codeblock: {
+                                    title: exampleName,
+                                    tabs: [
+                                        {
+                                            title: "application/json", // TODO: support multiple types
+                                            language: "json",
+                                            code: JSON.stringify(data.value, null, 2) || "",
+                                        }
+                                    ]
+                                }
+                            })
+                        })
+
+                        if (namedExamples.length === 1) {
+                            const firstCodeblock = namedExamples[0].codeblock
+
+                            tabs.push(
+                                ...firstCodeblock.tabs.map(tab => ({
+                                    ...tab,
+                                    title: contentType
+                                }))
+                            )
+                        } else {
+                            exampleGroups.push({
+                                description: "",
+                                examples: namedExamples
+                            })
+                        }
+
+                        continue
+                    }
+                } else if (content.example) {
+                    responseData = content.example
+                }
+
+                // If no example found, generate sample data from schema
+                if (!responseData) {
+                    responseData = OpenAPISampler.sample(sanitizeSchema(schema))
+                }
+
+                let extension = "text"
+                switch (contentType) {
+                    case "application/json":
+                    case "application/problem+json":
+                    case "application/vnd.api+json": {
+                        extension = "json"
+                        break
+                    }
+                    case "application/xml":
+                    case "text/xml":
+                    case "application/problem+xml": {
+                        extension = "xml"
+                        break
+                    }
+                }
+
+                tabs.push({
+                    title: contentType,
+                    language: extension,
+                    code: JSON.stringify(responseData, null, 2) || "",
+                })
+            }
+
+            if (tabs.length > 0) {
+                examples.push({
+                    codeblock: {
+                        title: status,
+                        tabs
+                    }
+                })
+            }
+        })
+
+        if (examples.length > 0) {
+            exampleGroups.push({
+                description: "Example response",
+                examples
+            })
+        }
+    }
+
+    return exampleGroups
+}
+
+/**
+ * fixAllOfBug fixes below case:
+ *
+ * ```yaml
+ * allOf:
+ *   - $ref: '#/components/schemas/SomeSchema'
+ *   - type: object
+ *     required:
+ *     properties:
+ * ```
+ *
+ */
+function fixAllOfBug(schema: JSONSchema7) {
+    const modifiedSchema = {...schema}
+
+    if (schema?.allOf) {
+        schema.allOf.forEach((prop, i) => {
+            const propObj = prop as object
+
+            if ("properties" in propObj && !propObj["properties"]) {
+                delete modifiedSchema.allOf?.[i]
+            }
+        })
+    }
+
+    return modifiedSchema
+}
+
+
+function sanitizeSchema(
+    schema: any,
+    vistedExamples: Map<JSONSchema7 | JSONSchema7[], any> = new Map(),
+    parent?: any
+): any {
+    if (vistedExamples.has(schema)) {
+        const cached = vistedExamples.get(schema);
+
+        if (typeof cached === 'object') {
+            return JSON.parse(JSON.stringify(cached)); // Return a deep copy of the cached schema
+        }
+
+        return cached
+    }
+
+    if (parent) {
+        vistedExamples.set(schema, parent);
+    }
+
+    if (!schema || typeof schema !== 'object') {
+        vistedExamples.set(schema, schema);
+        return schema;
+    }
+
+    if (Array.isArray(schema)) {
+        const v = schema.map(item => sanitizeSchema(item, vistedExamples));
+        vistedExamples.set(schema, v);
+        return v;
+    }
+
+    const cleaned: any = {};
+    for (const [key, value] of Object.entries(schema)) {
+        if (key === "__UNSAFE_refPath") {
+            continue;
+        }
+        if (!BUILT_IN_PROPERTIES[key]) {
+            cleaned[key] = sanitizeSchema(value, vistedExamples, cleaned);
+        }
+    }
+    vistedExamples.set(schema, cleaned);
+    return cleaned;
+}

package/src/{parameters.ts → converters/oas-parameters.ts}

@@ -1,6 +1,9 @@
 import {OpenAPIV3} from "openapi-types";
+
 import {DefinitionProperty} from "@xyd-js/uniform";
 
+import { schemaObjectToUniformDefinitionPropertyMeta } from "../oas-core";
+
 // oapParametersToDefinitionProperties converts OpenAPI parameters to uniform DefinitionProperties
 export function oapParametersToDefinitionProperties(
     parameters: OpenAPIV3.ParameterObject[]
@@ -14,12 +17,23 @@ export function oapParametersToDefinitionProperties(
 
         const schema = param.schema as OpenAPIV3.SchemaObject
 
+        const meta = [
+            ...(schemaObjectToUniformDefinitionPropertyMeta(schema, param.name) || []),
+            ...(schemaObjectToUniformDefinitionPropertyMeta(param, param.name) || []),
+        ]
+
+        let oapV2Type = ""
+        if ("type" in param) {
+            oapV2Type = param.type as string
+        }
+        
         const property: DefinitionProperty = {
             name: param.name,
-            type: schema.type || "",
-            description: param.description || ""
+            type: schema?.type || oapV2Type || "",
+            description: param.description || "",
+            meta
         }
-
+    
         parameterIn[param.in].push(property)
     })