docs(downgrader): document the four exports and the output openapi version

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.

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<T = unknown>(
   schema: OpenAPIV3_1.SchemaObject<T>,
 ): OpenAPIV3_0.ReferenceObject | OpenAPIV3_0.SchemaObject<T> {

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<T = unknown>(
   schema: OpenAPIV3_2.SchemaObject<T>,
 ): OpenAPIV3_1.SchemaObject<T> {