{"record":{"id":"fe27c89ab5013e31","repo":"GitbookIO/gitbook","slug":"v2-conversion","errorCode":"v2-conversion","errorMessage":"Failed to convert Swagger 2.0 to OpenAPI 3.1.1","messagePattern":"Failed to convert Swagger 2\\.0 to OpenAPI 3\\.1\\.1","errorType":"validation","errorClass":"OpenAPIParseError","httpStatus":null,"severity":"error","filePath":"packages/openapi-parser/src/v2.ts","lineNumber":27,"sourceCode":" */\nexport async function convertOpenAPIV2ToOpenAPIV3(\n    input: ParseOpenAPIInput\n): Promise<ParseOpenAPIResult> {\n    const result = upgradeFromInput(input);\n    return parseOpenAPIV3({ ...input, rootURL: input.rootURL, value: result.specification });\n}\n\n/**\n * Upgrade a Swagger 2.0 schema to an OpenAPI 3.0 schema.\n * This function will throw an error if the conversion fails.\n */\nfunction upgradeFromInput(input: ParseOpenAPIInput) {\n    const { value, rootURL } = input;\n    try {\n        return upgrade(value);\n    } catch (error) {\n        if (error instanceof Error) {\n            throw new OpenAPIParseError('Failed to convert Swagger 2.0 to OpenAPI 3.1.1', {\n                code: 'v2-conversion',\n                rootURL,\n                cause: error,\n            });\n        }\n\n        throw error;\n    }\n}\n","sourceCodeStart":9,"sourceCodeEnd":37,"githubUrl":"https://github.com/GitbookIO/gitbook/blob/db67585ee243d063c459a855988f21612cea9c95/packages/openapi-parser/src/v2.ts#L9-L37","documentation":"The openapi-parser first tries to upgrade Swagger 2.0 documents to OpenAPI 3.1.1; when the internal upgrade() conversion throws, it wraps the failure as OpenAPIParseError with code 'v2-conversion'. It means the document was recognized as v2 but its structure could not be transformed — usually schema constructs the converter can't map.","triggerScenarios":"Feeding a Swagger 2.0 spec containing constructs the upgrader chokes on — unusual $ref placements, non-standard type coercion cases, malformed definitions, or extension fields (x-*) with unexpected value shapes — so the upgrade pass throws an Error.","commonSituations":"Legacy enterprise Swagger 2.0 specs with hand-edited definitions; specs generated by old tooling (Swagger Editor 2.x, SoapUI) with quirks; docs that are actually invalid Swagger 2.0 but superficially parseable.","solutions":["Inspect error.cause — the underlying upgrade error names the exact failing construct","Validate/fix the spec with a Swagger 2.0 linter (swagger-cli validate) before passing it in","If possible, convert the document manually with swagger2openapi (with --warnOnly to see all issues), fix reported nodes, then serve the converted 3.x spec","As a stopgap, isolate and remove/simplify the offending definition and retry parsing"],"exampleFix":"# before\n# feed legacy swagger.yaml directly\n\n# after\nnpx swagger2openapi legacy-swagger.yaml -o openapi3.json\n# fix any reported conversion warnings, then:\n# point the GitBook OpenAPI block at openapi3.json","handlingStrategy":"try-catch","validationCode":"// Pre-convert with warnings surfaced before rendering\nimport { convertOpenAPIV2ToOpenAPIV3 } from '@gitbook/openapi-parser';\nawait convertOpenAPIV2ToOpenAPIV3({ value, rootURL }); // throws early with cause","typeGuard":"function isV2ConversionError(e: unknown): e is OpenAPIParseError {\n    return e instanceof OpenAPIParseError && e.code === 'v2-conversion';\n}","tryCatchPattern":"try {\n    const result = await parseOpenAPI({ value: text, rootURL: url });\n} catch (e) {\n    if (isV2ConversionError(e)) {\n        console.error('Cause:', e.cause);\n        return renderSpecConversionNotice(url);\n    }\n    throw e;\n}","preventionTips":["Validate Swagger 2.0 specs with swagger-cli before publishing","Convert specs to OpenAPI 3.x upstream with swagger2openapi and commit the result","Inspect error.cause to find the exact node the upgrader failed on"],"tags":["openapi","swagger","conversion","openapi-parser"],"backgroundTag":"openapi-conversion-failed","analyzedSha":"db67585ee243d063c459a855988f21612cea9c95","analyzedAt":"2026-08-28T17:49:47.831Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}