@xyd-js/openapi 0.1.0-build.168

package/src/converters/oas-paths.ts

@@ -0,0 +1,354 @@
+import {OpenAPIV3} from "openapi-types";
+
+import {
+    Definition,
+    ExampleGroup,
+    Reference,
+    ReferenceCategory,
+    OpenAPIReferenceContext,
+    DefinitionVariantOpenAPIMeta,
+    DefinitionVariant,
+    DefinitionOpenAPIMeta,
+    SymbolDef,
+    DefinitionProperty
+} from "@xyd-js/uniform";
+
+import {oapParametersToDefinitionProperties} from "./oas-parameters";
+import {oapRequestBodyToDefinitionProperties} from "./oas-requestBody";
+import {oasResponseToDefinitionProperties} from "./oas-responses";
+import {
+    httpMethodToUniformMethod,
+    slug
+} from "../utils";
+import {OasJSONSchema} from "../types";
+import path from "node:path";
+
+// oapPathToReference converts an OpenAPI path to a uniform Reference
+export function oapPathToReference(
+    schema: OpenAPIV3.Document,
+    httpMethod: string,
+    path: string,
+    oapPath: OpenAPIV3.PathItemObject,
+): Reference | null {
+    const mType = httpMethodToUniformMethod(httpMethod)
+
+    if (!mType) {
+        console.error(`Unsupported method: ${httpMethod}`)
+        return null
+    }
+
+    const definitions: Definition[] = []
+    const exampleGroups: ExampleGroup[] = []
+
+    const oapMethod = oapPath?.[httpMethod as keyof OpenAPIV3.PathItemObject] as OpenAPIV3.OperationObject
+    if (!oapMethod) {
+        return null
+    }
+
+    const tag = getFirstTag(oapMethod)
+    const group = [tag]
+
+    const endpointRef: Reference = {
+        title: title(oapMethod, httpMethod, path),
+        canonical: canonical(oapMethod, httpMethod, path),
+        description: oapMethod?.description || oapMethod?.summary,
+        type: mType,
+        category: ReferenceCategory.REST,
+
+        context: {
+            method: httpMethod,
+            path: `${encodeURIComponent(path)}`,
+            fullPath: path,
+            group,
+        } as OpenAPIReferenceContext,
+
+        examples: {
+            groups: exampleGroups,
+        },
+        definitions: definitions,
+    }
+
+    if (oapMethod.parameters) {
+        const parameters = oapMethod.parameters as OpenAPIV3.ParameterObject[]
+
+        const paramtersMap = oapParametersToDefinitionProperties(parameters)
+
+        Object.entries(paramtersMap).forEach(([key, definitionProperties]) => {
+            let title: string
+
+            switch (key) {
+                case 'path':
+                    title = "Path parameters"
+                    break
+                case 'query':
+                    title = "Query parameters"
+                    break
+                case 'header':
+                    title = "Headers"
+                    break
+                default:
+                    console.error(`Unsupported parameter type: ${key} for ${httpMethod} ${path}`)
+                    return
+            }
+
+            definitions.push({
+                title,
+                properties: definitionProperties
+            })
+        })
+    }
+
+    definitions.push(...oapOperationToDefinitions(oapMethod))
+
+    // TODO: !!!! better api !!!!
+    endpointRef.__UNSAFE_selector = function __UNSAFE_selector(selector: string) {
+        switch (selector) {
+            case "[schema]": {
+                return schema
+            }
+            case "[method]": {
+                return {
+                    oapPath,
+                    httpMethod,
+                    path
+                }
+            }
+
+            case "[method] [path]": {
+                return oapMethod
+            }
+            default:
+                return null
+        }
+    }
+
+    return endpointRef
+}
+
+function oapOperationToDefinitions(
+    oapMethod: OpenAPIV3.OperationObject,
+): Definition[] {
+    const definitions: Definition[] = []
+
+    if (oapMethod.requestBody) {
+        const definition = oapRequestOperationToUniformDefinition(oapMethod)
+        definitions.push(definition)
+    }
+
+    if (oapMethod.responses) {
+        const definition = oapResponseOperationToUniformDefinition(oapMethod)
+        definitions.push(definition)
+    }
+
+    return definitions
+}
+
+function oapRequestOperationToUniformDefinition(
+    oapOperation: OpenAPIV3.OperationObject,
+): Definition {
+    const reqBody = oapOperation.requestBody as OpenAPIV3.RequestBodyObject
+    const variants: DefinitionVariant<DefinitionVariantOpenAPIMeta>[] = []
+
+    for (const contentType of Object.keys(reqBody.content)) {
+        const schema = reqBody.content[contentType]?.schema as OpenAPIV3.SchemaObject
+
+        let properties: DefinitionProperty[] = []
+        let rootProperty: DefinitionProperty | undefined
+        let propertiesResp = oapRequestBodyToDefinitionProperties(reqBody, contentType) || []
+
+        if (Array.isArray(propertiesResp)) {
+            properties = propertiesResp
+        } else {
+            rootProperty = propertiesResp
+        }
+
+        const meta: DefinitionVariantOpenAPIMeta[] = [
+            {
+                name: "contentType",
+                value: contentType || "",
+            },
+        ]
+
+        if (schema?.required) {
+            meta.push({
+                name: "required",
+                value: schema.required ? "true" : "false",
+            })
+        }
+
+        variants.push({
+            title: contentType,
+            description: schema.description || "",
+            properties,
+            rootProperty,
+            meta,
+            symbolDef: definitionPropertyTypeDef(schema),
+        })
+    }
+
+    const meta: DefinitionOpenAPIMeta[] = []
+
+    if (reqBody.required) {
+        meta.push({
+            name: "required",
+            value: "true",
+        })
+    }
+
+    return {
+        title: 'Request body',
+        variants,
+        properties: [],
+        meta
+    }
+}
+
+export function oapResponseOperationToUniformDefinition(
+    oapOperation: OpenAPIV3.OperationObject,
+): Definition {
+
+    const responses = oapOperation.responses as OpenAPIV3.ResponsesObject
+
+    const variants: DefinitionVariant<DefinitionVariantOpenAPIMeta>[] = []
+
+    Object.keys(responses).forEach((code) => {
+        const responseObject = responses[code] as OpenAPIV3.ResponseObject
+        if (!responseObject?.content) {
+            variants.push({
+                title: code,
+                description: responseObject.description,
+                properties: [],
+                meta: [
+                    {
+                        name: "status",
+                        value: code || "",
+                    },
+                ],
+            })
+            return null
+        }
+
+        const contentTypes = Object.keys(responseObject.content)
+
+        for (const contentType of contentTypes) {
+            let properties: DefinitionProperty[] = []
+            let rootProperty: DefinitionProperty | undefined
+            const schema = responseObject.content[contentType]?.schema as OpenAPIV3.SchemaObject
+            const respProperties = oasResponseToDefinitionProperties(responses, code, contentType) || []
+
+            if (respProperties && "properties" in respProperties && respProperties?.properties) {
+                if (Array.isArray(respProperties.properties)) {
+                    properties = respProperties.properties
+                } else {
+                    rootProperty = respProperties.properties
+                }
+            }
+
+            let definitionDescription = ""
+            if ("description" in respProperties) {
+                definitionDescription = respProperties.description || ""
+            }
+
+            variants.push({
+                title: code,
+                description: responseObject.description,
+                properties,
+                rootProperty,
+                meta: [
+                    {
+                        name: "status",
+                        value: code || "",
+                    },
+                    {
+                        name: "contentType",
+                        value: contentType || "",
+                    },
+                    {
+                        name: "definitionDescription",
+                        value: definitionDescription
+                    }
+                ],
+                symbolDef: definitionPropertyTypeDef(schema),
+            })
+        }
+
+    })
+
+    return {
+        title: 'Response',
+        variants,
+        properties: []
+    }
+}
+
+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 title(
+    oapMethod: OpenAPIV3.OperationObject,
+    httpMethod: string,
+    httpPath: string,
+) {
+    const tit = oapMethod?.summary || oapMethod.operationId || ""
+    if (tit) {
+        return tit
+    }
+
+    if (!httpMethod || !httpPath) {
+        throw new Error("httpMethod and path are required to generate title")
+    }
+
+    return path.join(httpMethod, cleanPath(httpPath))
+}
+
+function canonical(
+    oapMethod: OpenAPIV3.OperationObject,
+    httpMethod: string,
+    httpPath: string,
+) {
+    let canon = oapMethod.operationId || slug(oapMethod?.summary || "")
+
+    if (canon) {
+        return canon
+    }
+
+    if (!httpMethod || !httpPath) {
+        throw new Error("httpMethod and path are required to generate canonical")
+    }
+
+    return path.join(httpMethod, cleanPath(httpPath))
+}
+
+function getFirstTag(oapMethod: OpenAPIV3.OperationObject) {
+    for (const tag of oapMethod?.tags || []) {
+        return tag
+    }
+
+    return ""
+}
+
+// Helper function to remove curly braces from path parameters
+function cleanPath(httpPath: string): string {
+    return httpPath.replace(/\{([^}]+)\}/g, '$1')
+}

package/src/converters/oas-requestBody.ts

@@ -0,0 +1,57 @@
+import {OpenAPIV3} from "openapi-types";
+
+import {DefinitionProperty, DEFINED_DEFINITION_PROPERTY_TYPE} from "@xyd-js/uniform";
+
+import {schemaObjectToUniformDefinitionProperties} from "../oas-core";
+
+// oapRequestBodyToDefinitionProperties converts OpenAPI request body to uniform DefinitionProperties
+export function oapRequestBodyToDefinitionProperties(
+    reqBody: OpenAPIV3.RequestBodyObject,
+    contentType: string
+): DefinitionProperty[] | DefinitionProperty | null {
+    const schema = reqBody.content[contentType].schema as OpenAPIV3.SchemaObject
+    if (!schema) {
+        return null
+    }
+
+    let schemaObject: OpenAPIV3.SchemaObject | undefined
+
+    if (schema.allOf || schema.anyOf || schema.oneOf) {
+        return schemaObjectToUniformDefinitionProperties(schema)
+    }
+
+    let array = false
+
+    switch (schema.type) {
+        case 'object': {
+            schemaObject = schema
+            break
+        }
+        case 'array': {
+            const arrSchema = schema as OpenAPIV3.ArraySchemaObject
+            const items = arrSchema.items as OpenAPIV3.SchemaObject
+
+            schemaObject = items
+            array = true
+
+            break
+        }
+        default:
+            // TODO: primitive types ???
+            break
+    }
+
+    if (!schemaObject) {
+        return null
+    }
+
+    const properties = schemaObjectToUniformDefinitionProperties(schemaObject)
+    if (array) {
+        return {
+            type: DEFINED_DEFINITION_PROPERTY_TYPE.ARRAY,
+            properties,
+        } as DefinitionProperty
+    }
+
+    return properties
+}

package/src/converters/oas-responses.ts

@@ -0,0 +1,76 @@
+import {OpenAPIV3} from "openapi-types";
+import {DefinitionProperty, DEFINED_DEFINITION_PROPERTY_TYPE} from "@xyd-js/uniform";
+
+import {schemaObjectToUniformDefinitionProperties} from "../oas-core";
+
+export function oasResponseToDefinitionProperties(
+    responses: OpenAPIV3.ResponsesObject,
+    code: string,
+    contentType: string,
+): {
+    properties: DefinitionProperty | DefinitionProperty[],
+    description?: string,
+} | null {
+    let schemaObject: OpenAPIV3.SchemaObject | undefined
+    let responseObject: OpenAPIV3.ResponseObject | undefined
+
+    if (responses[code]) {
+        responseObject = responses[code] as OpenAPIV3.ResponseObject
+        if (!responseObject?.content) {
+            return null
+        }
+
+        schemaObject = responseObject?.content[contentType]?.schema as OpenAPIV3.SchemaObject
+    }
+
+    if (!schemaObject) {
+        return {
+            properties: [
+                {
+                    description: responseObject?.description || "",
+                    name: "",
+                    type: ""
+                }
+            ],
+        }
+    }
+
+    let array = false
+
+    switch (schemaObject.type) {
+        case 'array':
+            const arrSchema = schemaObject as OpenAPIV3.ArraySchemaObject
+            const items = arrSchema.items as OpenAPIV3.SchemaObject
+
+            schemaObject = items
+            array = true
+        default:
+            break
+    }
+
+    const properties = schemaObjectToUniformDefinitionProperties(schemaObject, true)
+
+    let description = ""
+
+    if (schemaObject.allOf) {
+        for (const item of schemaObject.allOf) {
+           if ("description" in item) {
+               description += item.description + "\n";
+           }
+        }
+    }
+
+    if (array) {
+        return {
+            properties: {
+                type: DEFINED_DEFINITION_PROPERTY_TYPE.ARRAY,
+                properties,
+            } as DefinitionProperty
+        }
+    }
+
+    return {
+        properties: properties || [],
+        description: description || "",
+    }
+}

package/src/converters/oas-schema.ts

@@ -0,0 +1,141 @@
+import path from "node:path";
+
+import { OpenAPIV3 } from "openapi-types";
+import Oas from "oas";
+
+import type { Reference, OpenAPIReferenceContext, ReferenceContext } from "@xyd-js/uniform";
+
+import { SUPPORTED_HTTP_METHODS } from "../const";
+import { oapPathToReference } from "./oas-paths";
+import { oapExamples } from "./oas-examples";
+import { uniformOasOptions } from "../types";
+import { schemaComponentsToUniformReferences } from "./oas-componentSchemas";
+import {httpMethodToUniformMethod} from "../utils";
+
+// TODO: support one-of
+// TODO: support $ref - currently we use $refParser.dereference that converts $ref into objects
+// TODO: better method check system - currently we need to manually check that in few methods
+
+// oapSchemaToReferences converts an OpenAPI schema to a list of uniform References
+export function oapSchemaToReferences(
+    schema: OpenAPIV3.Document,
+    options?: uniformOasOptions,
+): Reference[] {
+    if (!schema) {
+        return []
+    }
+    const references: Reference[] = [];
+    const oas = new Oas(schema as any);
+
+    const server = schema.servers?.[0]?.url || ""
+
+    Object.entries(schema.paths).forEach(([endpointPath, oapPath]) => {
+        SUPPORTED_HTTP_METHODS.forEach((eachMethod) => {
+            const httpMethod = eachMethod.toLowerCase() as OpenAPIV3.HttpMethods
+
+            const found = httpMethodToUniformMethod(httpMethod)
+            if (!found) {
+                console.warn(`Unsupported method: ${httpMethod} for path: ${endpointPath}`)
+                return
+            }
+
+            // Check if this method/path combination should be included based on regions
+            if (options?.regions && options.regions.length > 0) {
+                const regionKey = `${eachMethod.toUpperCase()} ${endpointPath}`
+                    if (!options.regions.some(region => region === regionKey)) {
+                    return
+                }
+            }
+
+            const reference = oapPathToReference(
+                schema,
+                httpMethod,
+                endpointPath,
+                oapPath as OpenAPIV3.PathItemObject
+            )
+
+            if (reference) {
+                const ctx = reference.context as OpenAPIReferenceContext
+                ctx.path = endpointPath
+                ctx.fullPath = path.join(server, endpointPath)
+
+                const operation = oas.operation(endpointPath, httpMethod);
+                reference.examples.groups = oapExamples(oas, operation)
+
+                const scopes: string[] = []
+                const oapMethod = oapPath?.[httpMethod] as OpenAPIV3.OperationObject
+                if (schema?.security?.length) {
+                    for (const security of schema.security) {
+                        for (const securityKey of Object.keys(security)) {
+                            if (securityKey === "oauth2" || securityKey === "OAuth2") {
+                                const securityScopes = security[securityKey]
+                                if (Array.isArray(securityScopes)) {
+                                    scopes.push(...securityScopes)
+                                }
+                            }
+                        }
+                    }
+                }
+                if (oapMethod?.security) {
+                    if (!oapMethod?.security?.length) {
+                        scopes.length = 0
+                    }
+                    for (const security of oapMethod.security) {
+                        for (const securityKey of Object.keys(security)) {
+                            const securityScheme = schema?.components?.securitySchemes?.[securityKey]
+
+                            // TODO: support other scope-like security schemes
+                            if (securityScheme && "type" in securityScheme && securityScheme.type === "oauth2") {
+                                const methodScopes = security[securityKey]
+                                if (Array.isArray(methodScopes)) {
+                                    scopes.push(...methodScopes)
+                                }
+                            }
+                        }
+                    }
+                }
+
+                ctx.scopes = scopes
+
+                references.push(reference)
+            }
+        })
+    })
+
+    const schemas = schemaComponentsToUniformReferences(
+        schema,
+        options,
+    )
+    references.push(...schemas)
+
+    const tags = oas.getTags()
+    sortReferencesByTags(references, tags)
+
+    // TODO: in the future better API
+    // @ts-ignore
+    references.__internal_options = () => options
+
+    return references
+}
+
+function sortReferencesByTags(references: Reference[], tags: string[]) {
+    return references.sort((prev, next) => {
+        const aTags = prev.context?.group || []
+        const bTags = next.context?.group || []
+
+        // Find the first tag that exists in both arrays
+        for (const tag of tags) {
+            const aIndex = aTags.indexOf(tag)
+            const bIndex = bTags.indexOf(tag)
+
+            if (aIndex !== -1 && bIndex !== -1) {
+                return aIndex - bIndex
+            }
+            if (aIndex !== -1) return -1
+            if (bIndex !== -1) return 1
+        }
+
+        // If no matching tags found, sort by first tag
+        return (aTags[0] || '').localeCompare(bTags[0] || '')
+    })
+}

package/src/index.ts

@@ -0,0 +1,21 @@
+export * from "./const"
+
+export * from "./converters/oas-parameters"
+
+export * from "./converters/oas-paths"
+
+export * from "./oas-core"
+
+export * from "./converters/oas-requestBody"
+
+export * from "./converters/oas-responses"
+
+export * from "./converters/oas-schema"
+
+export * from "./utils"
+
+export * from "./xdocs/types"
+
+export {getXDocs} from "./xdocs"
+
+export {uniformPluginXDocsSidebar} from "./xdocs/pluginSidebar"