From 78459b5c2148f2701e9284ae0a69dd13c1aac0ba Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 24 Oct 2026 13:09:08 +0000 Subject: [PATCH] docs(downgrader): document the four exports and the output openapi version Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01Doek2EaqL6pLLJEyYo6FDr --- packages/downgrader/README.md | 2 ++ packages/downgrader/src/v3.1-to-v3.0.ts | 2 ++ packages/downgrader/src/v3.2-to-v3.1.ts | 2 ++ 3 files changed, 6 insertions(+) diff --git a/packages/downgrader/README.md b/packages/downgrader/README.md index 1f618a0..e70515c 100644 --- a/packages/downgrader/README.md +++ b/packages/downgrader/README.md @@ -55,6 +55,8 @@ downgradeSchemaV31ToV30({ type: ['string', 'null'] }) Each step can also be imported on its own from `@openapi-spec/downgrader/v3.2-to-v3.1` or `@openapi-spec/downgrader/v3.1-to-v3.0`. All types come from [`@openapi-spec/types`](https://github.com/middleapi/openapi-spec/blob/main/packages/types/README.md). +The output `openapi` is the latest patch release, `3.1.2` from `downgradeSpecV32ToV31` and `3.0.4` from `downgradeSpecV31ToV30`. Set it afterwards for another patch release, as oRPC does. + The input is never changed, and the output shares no plain objects or arrays with it. Input is read as JSON would see it: an object counts whatever realm it comes from or null prototype it has, as in a document oRPC returns, and a key holding `undefined`, as spreading options often leaves, counts as missing. Other values, such as a `Date`, are kept as they are. External `$ref`s are left as written, except in a 3.2 `content` map, where 3.1 allows none and the entry is removed. The files they point at are not converted, so bundle a multi-file document into one first. diff --git a/packages/downgrader/src/v3.1-to-v3.0.ts b/packages/downgrader/src/v3.1-to-v3.0.ts index 0b8ff35..ad46d48 100644 --- a/packages/downgrader/src/v3.1-to-v3.0.ts +++ b/packages/downgrader/src/v3.1-to-v3.0.ts @@ -806,10 +806,12 @@ function downgradeV30(root: unknown, convert: Convert): unknown { return out } +/** Downgrades an OpenAPI 3.1 document to 3.0, setting `openapi` to `3.0.4`. The input is never changed. */ export function downgradeSpecV31ToV30(spec: OpenAPIV3_1.OpenAPIObject): OpenAPIV3_0.OpenAPIObject { return downgradeV30(spec, convertDocument) as OpenAPIV3_0.OpenAPIObject } +/** Downgrades a 3.1 Schema Object to 3.0. Local `$ref`s resolve against the schema itself. The input is never changed. */ export function downgradeSchemaV31ToV30( schema: OpenAPIV3_1.SchemaObject, ): OpenAPIV3_0.ReferenceObject | OpenAPIV3_0.SchemaObject { diff --git a/packages/downgrader/src/v3.2-to-v3.1.ts b/packages/downgrader/src/v3.2-to-v3.1.ts index 29fe9b6..6b53642 100644 --- a/packages/downgrader/src/v3.2-to-v3.1.ts +++ b/packages/downgrader/src/v3.2-to-v3.1.ts @@ -304,10 +304,12 @@ function convertDocument(value: unknown, ctx: Context): unknown { return convertObject(value, ctx, DOCUMENT_FIELDS, finishDocument) } +/** Downgrades an OpenAPI 3.2 document to 3.1, setting `openapi` to `3.1.2`. The input is never changed. */ export function downgradeSpecV32ToV31(spec: OpenAPIV3_2.OpenAPIObject): OpenAPIV3_1.OpenAPIObject { return downgrade(spec, convertDocument) as OpenAPIV3_1.OpenAPIObject } +/** Downgrades a 3.2 Schema Object to 3.1. The input is never changed. */ export function downgradeSchemaV32ToV31( schema: OpenAPIV3_2.SchemaObject, ): OpenAPIV3_1.SchemaObject {