@kubb/adapter-oas 5.8.4 → 5.9.1

package/docs/options.md

@@ -12,7 +12,7 @@ Pass these options to `adapterOas()`. All of them are optional.
 | [`discriminator`](#discriminator)     | How `discriminator` fields are interpreted.                  |
 | [`enums`](#enums)                     | Where inline enums live.                                     |
 | [`dateType`](#datetype)               | How `date-time`, `date`, and `time` schemas are represented. |
-| [`integerType`](#integertype)         | How integers map to TypeScript.                              |
+| [`integerType`](#integertype)         | How `int64` and `uint64` integers map to TypeScript.         |
 | [`unknownType`](#unknowntype)         | Type for schemas Kubb cannot infer.                          |
 | [`emptySchemaType`](#emptyschematype) | Type for empty schemas.                                      |
 | [`enumSuffix`](#enumsuffix)           | Suffix for derived enum names.                               |
@@ -205,7 +205,7 @@ adapterOas({
 
 ### integerType
 
-How `type: integer` (and `format: int64`) maps to TypeScript.
+How a schema with `format: int64` or `format: uint64` maps to TypeScript. Other integers, such as `type: integer` without a format or with `format: int32`, always map to `number`.
 
 |          |                        |
 | -------- | ---------------------- |

package/docs/overview.md

@@ -1,22 +1,30 @@
-# OpenAPI adapter
+# OpenAPI
 
-The OpenAPI adapter reads an OpenAPI 2.0, 3.0, or 3.1 document and converts every schema and operation into Kubb's AST. Every plugin in the build generates code from that AST.
+The OpenAPI adapter is the first step of every build. It converts your spec into Kubb's AST, and every plugin generates code from that AST, so the adapter's options apply to all of them.
 
-Kubb uses `adapterOas()` by default. Set it on `defineConfig.adapter` only to change its [options](https://kubb.dev/extensions/kubb-labs/adapter-oas/options). The options apply to every plugin in the build.
+The adapter downloads a remote `input` URL and any remote `$ref`s with a plain GET request, without credentials. It also reads the local files that external `$ref`s point to, even outside the spec's folder, and never writes files.
+
+## Setup
+
+Kubb uses `adapterOas()` by default, so no setup is needed. Set `adapter` in `defineConfig` only to change its options.
 
 ## Options worth knowing
 
 - `validate` checks the spec before parsing and reports each problem as a warning. Turn it off to speed up a large spec. Run `kubb validate` to list every error.
-- `dateType` sets how `date-time`, `date`, and `time` schemas are represented: ISO strings (the default), strings with or without a timezone offset, or JavaScript `Date` objects. Pass an object to set each format on its own.
-- `integerType` defaults to `'bigint'`, which is exact for 64-bit IDs but does not survive `JSON.stringify`. Choose `'number'` for most JSON APIs.
+- `dateType` sets how `date-time`, `date`, and `time` schemas are typed. Choose ISO strings (the default), `date-time` strings with or without a timezone offset, or JavaScript `Date` objects. Pass an object to set each format on its own.
+- `integerType` sets how `int64` and `uint64` schemas are typed. The default `'bigint'` is exact for 64-bit IDs but does not survive `JSON.stringify`. Choose `'number'` for most JSON APIs.
 - `unknownType` and `emptySchemaType` set the type for schemas Kubb cannot infer and for empty schemas (`{}`).
 - `discriminator: 'propagate'` writes the discriminator's literal value into each child schema, so each branch is typed precisely.
 - `enums: 'root'` lifts inline enums to reusable top-level schemas, named with `enumSuffix` (`PetStatusEnum`).
 - `server` picks the entry in the spec's `servers` array that becomes the base URL and fills in its variables. It does not change where a generated client sends requests. Use the client plugin's own `baseURL` for that.
-- `contentType` picks the media type when an operation defines several. Without it, Kubb uses the first JSON media type.
+- `contentType` picks one media type when an operation declares several. Without it, Kubb keeps every media type the operation declares.
+
+See [Options](https://kubb.dev/extensions/kubb-labs/adapter-oas/options) for every option and its default.
 
 ## Example
 
+The config below types dates as `Date` objects and 64-bit integers as numbers.
+
 ```typescript [kubb.config.ts]
 import { defineConfig } from 'kubb/config'
 import { adapterOas } from '@kubb/adapter-oas'
@@ -26,6 +34,8 @@ export default defineConfig({
   input: './petStore.yaml',
   output: { path: './src/gen' },
   adapter: adapterOas({ dateType: 'date', integerType: 'number' }),
-  plugins: [pluginTs()],
+  plugins: [
+    pluginTs(),
+  ],
 })
 ```

package/kubb-extension.json

@@ -59,7 +59,7 @@
       "key": "integerType",
       "path": ["integerType"],
       "label": "Integer Type",
-      "description": "How integer and int64 schemas map to TypeScript.",
+      "description": "How int64 and uint64 schemas map to TypeScript. Other integers stay numbers.",
       "type": "select",
       "default": "bigint",
       "choices": [
@@ -132,7 +132,7 @@
       "key": "contentType",
       "path": ["contentType"],
       "label": "Content Type",
-      "description": "Preferred media type when an operation defines several. Defaults to the first JSON media type in the spec.",
+      "description": "Media type to keep for request bodies and responses. Leave empty to keep every media type an operation declares.",
       "type": "text"
     },
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/adapter-oas",
-  "version": "5.8.4",
+  "version": "5.9.1",
   "description": "OpenAPI and Swagger adapter for Kubb. Parses and validates OAS 2.0/3.x specifications into a @kubb/ast RootNode for downstream code generation plugins.",
   "keywords": [
     "adapter",
@@ -61,7 +61,7 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@kubb/kit": "5.8.4",
+    "@kubb/kit": "5.9.1",
     "@readme/openapi-parser": "^9.1.0",
     "@scalar/openapi-upgrader": "^0.4.3",
     "api-ref-bundler": "0.5.1",