@fluojs/openapi 1.1.0 → 2.0.0

package/README.ko.md

@@ -20,6 +20,8 @@ fluo를 위한 descriptor-driven OpenAPI 3.1.0 문서 생성 패키지입니다.
 pnpm add @fluojs/openapi
 ```
 
+`@fluojs/openapi`는 Node.js `>=24.0.0 <27`을 지원하며 `engines.node`로 정확히 이 범위를 선언합니다. 이 package-owned 지원 계약은 Node 24 미만과 Node 27 이상을 제외하며 portable `@fluojs/runtime`에는 package-wide Node engine이 없습니다. 이전 1.x 릴리스는 `engines.node >=20.0.0`을 광고했습니다.
+
 ## 사용 시점
 
 - **Swagger UI**를 사용하여 REST API에 대한 대화형 문서를 제공하고 싶을 때.
@@ -35,7 +37,7 @@ pnpm add @fluojs/openapi
 ```typescript
 import { Controller, Get } from '@fluojs/http';
 import { Module } from '@fluojs/core';
-import { bootstrapNodeApplication } from '@fluojs/runtime/node';
+import { bootstrapNodeApplication } from '@fluojs/platform-nodejs';
 import { OpenApiModule, ApiOperation, ApiResponse, ApiTag } from '@fluojs/openapi';
 
 @ApiTag('Users')
@@ -74,9 +76,28 @@ await app.listen(3000);
 
 ## 핵심 기능
 
+### 빈 decorator options
+
+`@ApiOperation()` / `@ApiOperation(undefined)`와 `@ApiBody()` / `@ApiBody(undefined)`는
+기존 `{}` 의미를 사용합니다. Summary, description, deprecated, required, schema를 임의로
+생성하지 않습니다. 빈 body metadata는 DTO에서 추론한 body를 유지하고, 추론한 body가 없으면
+`requestBody`를 추가하지 않습니다. 빈 write도 stacking의 이전 metadata를 덮어쓸 수 있으므로
+decorator 자체 생략과 항상 같지는 않습니다. 기존 적용 시 `null` 실패를 유지합니다.
+`ApiTag(tag)`, `ApiResponse(status, options?)`, parameter/security name은 계속 필수이며
+지원하는 OpenAPI Path Item method 집합은 바뀌지 않습니다.
+
 ### 자동 명세 생성
 fluo는 `sources`와 `descriptors`로 전달된 controller 및 handler descriptor만 조사하여 OpenAPI 3.1.0 문서를 작성합니다. 이 명시적 입력 집합의 경로, 메서드, 파라미터, 요청 바디가 포함되며, controller를 application module에 import하는 것만으로는 자동 추가되지 않습니다.
 
+### OpenAPI 3.1 Path Item 검증
+Builder는 표준 Path Item operation인 `get`, `put`, `post`, `delete`, `options`, `head`, `patch`, `trace`만 생성합니다. Fluo catch-all `ALL` descriptor는 runtime routing 입력이지 OpenAPI operation이 아니므로, 비표준 `all` key로 직렬화하지 않고 문서 생성을 거부합니다. 지원하지 않는 다른 descriptor method도 같은 path-specific error로 실패합니다.
+
+`documentTransform` 이후에는 모든 Path Item을 다시 검증합니다. Transform은 OpenAPI 3.1 operation(`trace` 포함), fixed field(`$ref`, `summary`, `description`, `servers`, `parameters`), `x-*` specification extension을 사용할 수 있습니다. `all`, `query` 또는 기타 알 수 없는 key는 문서가 노출되기 전에 생성을 실패시킵니다.
+
+### 2.0으로 마이그레이션
+
+업그레이드하기 전에 모든 `@All()` route 또는 custom handler descriptor를 각각 지원되는 HTTP method route로 바꾸거나 OpenAPI 입력에서 제외하세요. `documentTransform`에서는 `all`, `query` 같은 비표준 Path Item key를 제거하고 표준 operation, fixed field, `x-*` extension만 유지하세요. 지원하지 않는 입력은 이제 잘못된 문서를 생성하는 대신 문서 생성 단계에서 예외를 발생시킵니다.
+
 ### 응답 미디어 타입
 HTTP 핸들러가 `@fluojs/http`의 `@Produces(...)`를 선언하면, 생성된 OpenAPI 응답은 해당 미디어 타입을 response `content` 키로 사용합니다. 예를 들어 `@ApiResponse(...)` 스키마가 있는 핸들러에 `@Produces('application/json', 'application/problem+json')`를 붙이면, `application/json`만으로 되돌아가지 않고 두 미디어 타입 모두 같은 응답 스키마로 방출합니다.
 
@@ -89,13 +110,19 @@ Builder는 handler 반환값이나 TypeScript 반환 타입을 검사해 respons
 ### 통합 DTO 스키마
 `@fluojs/validation`과 함께 DTO binding 및 validation metadata에서 request schema를 파생합니다. Response DTO는 `@ApiResponse(..., { type: ResponseDto })` 또는 `extraModels`처럼 명시적으로 참조할 때만 OpenAPI component가 됩니다.
 
+### OpenAPI 3.1 배타적 경계
+`OpenApiSchemaObject`는 OpenAPI 3.1의 숫자 `exclusiveMinimum` 및 `exclusiveMaximum` 값을 받으면서 기존 boolean metadata와의 호환성도 유지합니다. `minimum` 또는 `maximum`과 함께 사용한 `true` 플래그는 생성 문서에서 대응하는 숫자 배타적 경계로 변환되고, `false` 플래그는 생략되는 대신 포괄 경계는 유지됩니다. 유한한 숫자 배타적 경계는 변경 없이 통과합니다. 유한한 대응 경계가 없는 `true` 플래그나 유한하지 않은 숫자 배타적 경계는 잘못된 OpenAPI 3.1 schema를 생성하는 대신 문서 생성을 실패시킵니다. 같은 정규화는 문서가 노출되기 전에 `documentTransform` 이후에도 실행됩니다.
+
+### OpenAPI 3.1 Nullable 스키마
+`OpenApiSchemaObject`는 호환성 입력으로 legacy boolean `nullable` keyword를 계속 받지만 생성되는 OpenAPI 3.1 문서에는 이를 내보내지 않습니다. `nullable: true`는 scalar 및 array constraint를 보존하면서 선언된 `type` union에 `null`을 추가합니다. `$ref` schema를 포함해 `type`이 없는 schema는 `{ type: 'null' }`과의 `anyOf` union으로 변환됩니다. `nullable: false`는 schema를 바꾸지 않고 제거됩니다. 기존 null union에는 `null`을 중복 추가하지 않으며, 이 재귀 정규화는 `documentTransform` 뒤에도 실행됩니다.
+
 ### 버전 관리 지원
 `@fluojs/http`의 URI 기반 버전 관리를 자동으로 처리합니다. OpenAPI 경로에 해결된 버전 경로가 올바르게 반영됩니다.
 
 ### 보안 문서화
-`@ApiBearerAuth()` 및 `@ApiSecurity()`를 사용하여 Bearer 토큰이나 API 키와 같은 보안 요구사항을 쉽게 문서화할 수 있습니다.
+`@ApiBearerAuth()` 및 `@ApiSecurity(name, scopes?)`를 사용하여 Bearer 토큰이나 API 키와 같은 보안 요구사항을 쉽게 문서화할 수 있습니다.
 
-같은 scheme에 대해 여러 `@ApiSecurity()` 데코레이터를 쌓으면, 해당 scheme의 scope가 하나의 누적 OpenAPI security requirement로 병합됩니다. 따라서 라우트가 `['reports:read']`와 `['reports:write', 'reports:read']`처럼 겹치는 scope를 선언해도 OAuth 스타일 요구사항은 결정적으로 유지되며, 서로 다른 scheme은 별도 requirement로 남습니다.
+같은 scheme에 대해 여러 `@ApiSecurity(name, scopes?)` 데코레이터를 쌓으면, 해당 scheme의 scope가 하나의 누적 OpenAPI security requirement로 병합됩니다. 따라서 라우트가 `['reports:read']`와 `['reports:write', 'reports:read']`처럼 겹치는 scope를 선언해도 OAuth 스타일 요구사항은 결정적으로 유지되며, 서로 다른 scheme은 별도 requirement로 남습니다.
 
 ### 결정적인 Swagger UI 자산
 `ui: true`를 활성화하면 생성되는 `/docs` 페이지는 정확한 `swagger-ui-dist` 버전의 자산을 참조하여 패키지 릴리스마다 동일한 동작을 유지합니다. 오프라인 또는 CSP 제어 환경에서 자체 호스팅 자산이 필요하면 `swaggerUiAssets.cssUrl`과 `swaggerUiAssets.jsBundleUrl`을 설정하세요. 생성된 HTML은 해당 URL을 이스케이프하며 Swagger UI 인스턴스를 `window.ui`에 노출하지 않습니다.
@@ -135,6 +162,13 @@ Path는 `@fluojs/http` route grammar를 따르며 중복 slash와 trailing slash
 ### Async 등록과 옵션
 title/version/source 설정이 DI나 async setup에서 나오는 경우 `OpenApiModule.forRootAsync(...)`를 사용합니다. 등록 시점의 `documentPath`와 `uiPath`는 `inject`, `useFactory` 옆에 두고, factory에서는 `sources`, `descriptors`, `securitySchemes`, `extraModels`, `defaultErrorResponsesPolicy`, `documentTransform`, `ui`, `swaggerUiAssets`를 반환합니다. `defaultErrorResponsesPolicy`는 기본적으로 표준 error response와 `ErrorResponse` schema를 주입하며, `documentTransform`은 문서 생성 뒤 제공되기 전에 실행됩니다.
 
+### NestJS 마이그레이션 계약 차이
+생성 문서는 NestJS Swagger와 일대일 호환 계층이 아닙니다. fluo는 기본적으로 명시적으로 선언한 응답을 대체하지 않으면서 `400`, `401`, `403`, `404`, `500` 응답과 공용 `ErrorResponse` schema를 추가합니다. 클라이언트를 다시 생성하기 전에 생성된 error contract를 검증하고, legacy 문서에 이 기본 응답이 들어가면 안 되는 경우 `defaultErrorResponsesPolicy: 'omit'`을 설정하세요.
+
+fluo는 controller tag, handler name, HTTP method, normalized path에서 각 `operationId`를 결정론적으로 만듭니다. 충돌에는 숫자 suffix가 붙습니다. 생성된 client가 legacy identifier에 의존한다면 문서를 제공하기 전에 `documentTransform`에서 생성된 operation ID를 변경하고, 변환된 문서를 client generator로 검증하세요.
+
+`forRootAsync(...)`에서는 `documentPath`와 `uiPath`의 route가 `useFactory(...)`가 resolve되기 전에 compile되므로 두 값은 바깥 registration option입니다. 이 path들은 `inject`와 `useFactory` 옆에 두고 factory에서는 document configuration만 반환하세요. factory가 반환한 path로는 이미 등록된 route를 다시 구성할 수 없습니다.
+
 ## 공개 API
 
 - `OpenApiModule`: OpenAPI 통합을 위한 메인 엔트리 포인트.
@@ -142,12 +176,13 @@ title/version/source 설정이 DI나 async setup에서 나오는 경우 `OpenApi
 - `ApiBody`, `ApiParam`, `ApiQuery`, `ApiHeader`, `ApiCookie`: 이름이 겹칠 때 추론된 요청 문서를 대체하는 명시적 요청 본문 및 파라미터 문서화 데코레이터.
 - `ApiBearerAuth`, `ApiSecurity`: 보안 요구사항 데코레이터.
 - `ApiExcludeEndpoint`: 특정 핸들러를 문서화에서 제외.
+- `ApiOperationOptions`, `ApiResponseOptions`, `ApiParameterOptions`, `ApiBodyOptions`: `@ApiOperation(...)`, `@ApiResponse(...)`, `@ApiParam(...)`, `@ApiQuery(...)`, `@ApiHeader(...)`, `@ApiCookie(...)`, `@ApiBody(...)`가 받는 데코레이터 옵션 타입.
 - `buildOpenApiDocument`: 프로그래밍 방식의 문서 빌더 (저수준).
 - `OpenApiHandlerRegistry`: 고급 통합에서 문서 생성 전에 handler descriptor를 스냅샷하는 mutable descriptor registry.
 - `getControllerTags`, `getMethodApiMetadata`: 고급 테스트와 통합 tooling을 위한 metadata reader.
 - `OpenApiModuleOptions`, `OpenApiAsyncModuleOptions`, `OpenApiRouteOptions`, `OpenApiSwaggerUiAssetsOptions`, `BuildOpenApiDocumentOptions`, `DefaultErrorResponsesPolicy`: module과 builder integration을 위한 option type.
 - `OpenApiDocument`, `OpenApiSecuritySchemeObject` 및 관련 OpenAPI shape type: 테스트, tooling, integration을 위한 typed document surface.
-- `OpenApiSchemaObject`: 명시적 `@ApiBody(...)` 및 `@ApiResponse(...)` 스키마를 위한 타입화된 스키마 표면입니다. OpenAPI 3.1 조합(`allOf`, `oneOf`, `anyOf`), 객체/배열 제약, examples/defaults, 읽기/쓰기/Deprecated 주석을 포함합니다.
+- `OpenApiSchemaObject`: 명시적 `@ApiBody(...)` 및 `@ApiResponse(...)` 스키마를 위한 타입화된 스키마 표면입니다. OpenAPI 3.1 조합(`allOf`, `oneOf`, `anyOf`), legacy `nullable` 입력과 호환되는 null union, 객체/배열 제약, examples/defaults, 읽기/쓰기/Deprecated 주석을 포함합니다.
 
 ## 관련 패키지
 

package/README.md

@@ -20,6 +20,8 @@ Descriptor-driven OpenAPI 3.1.0 document generation for fluo, with standard deco
 pnpm add @fluojs/openapi
 ```
 
+`@fluojs/openapi` supports Node.js `>=24.0.0 <27` and declares that exact range through `engines.node`. That package-owned support contract excludes Node versions below 24 and Node 27+; portable `@fluojs/runtime` has no package-wide Node engine. Earlier 1.x releases advertised `engines.node >=20.0.0`.
+
 ## When to Use
 
 - When you want to provide interactive documentation for your REST API using **Swagger UI**.
@@ -35,7 +37,7 @@ Register the `OpenApiModule` and pass `sources`, prebuilt `descriptors`, or both
 ```typescript
 import { Controller, Get } from '@fluojs/http';
 import { Module } from '@fluojs/core';
-import { bootstrapNodeApplication } from '@fluojs/runtime/node';
+import { bootstrapNodeApplication } from '@fluojs/platform-nodejs';
 import { OpenApiModule, ApiOperation, ApiResponse, ApiTag } from '@fluojs/openapi';
 
 @ApiTag('Users')
@@ -74,9 +76,28 @@ When a prebuilt descriptor and a discovered source resolve to the same OpenAPI p
 
 ## Core Capabilities
 
+### Empty decorator options
+
+`@ApiOperation()` / `@ApiOperation(undefined)` and `@ApiBody()` / `@ApiBody(undefined)`
+use the existing `{}` semantics. No summary, description, deprecated flag, required flag,
+or schema is invented. Empty body metadata preserves a DTO-inferred body and adds no
+`requestBody` when none is inferred. Empty writes can overwrite earlier stacked metadata,
+so these calls are not always equivalent to omitting the decorator. Existing application-time
+`null` failures remain. `ApiTag(tag)`, `ApiResponse(status, options?)`, and parameter/security
+names remain required; the supported OpenAPI Path Item methods do not change.
+
 ### Automated Specification Generation
 fluo inspects only the controllers and handler descriptors supplied through `sources` and `descriptors` to build an OpenAPI 3.1.0 document. This includes paths, methods, parameters, and request bodies for that explicit input set; importing a controller into an application module does not add it automatically.
 
+### OpenAPI 3.1 Path Item Validation
+The builder emits only standard Path Item operations: `get`, `put`, `post`, `delete`, `options`, `head`, `patch`, and `trace`. Fluo catch-all `ALL` descriptors are runtime routing inputs, not OpenAPI operations, so document generation rejects them instead of serializing a nonstandard `all` key. Unsupported descriptor methods fail with the same path-specific error.
+
+After `documentTransform`, every Path Item is validated again. Transforms may use the OpenAPI 3.1 operations (including `trace`), fixed fields (`$ref`, `summary`, `description`, `servers`, and `parameters`), and `x-*` specification extensions. Keys such as `all`, `query`, or other unknown fields fail document generation before the document is exposed.
+
+### Migrating to 2.0
+
+Before upgrading, replace every `@All()` route or custom handler descriptor with separate supported HTTP method routes, or exclude it from OpenAPI input. In `documentTransform`, remove nonstandard Path Item keys such as `all` and `query`; retain only standard operations, fixed fields, and `x-*` extensions. Unsupported input now throws during document generation instead of emitting an invalid document.
+
 ### Response Media Types
 When an HTTP handler declares `@Produces(...)` from `@fluojs/http`, generated OpenAPI responses use those media types as the response `content` keys. For example, `@Produces('application/json', 'application/problem+json')` on a handler with an `@ApiResponse(...)` schema emits both media types with the same response schema instead of silently falling back to only `application/json`.
 
@@ -89,13 +110,19 @@ The builder does not inspect handler return values or TypeScript return types to
 ### Integrated DTO Schemas
 Works with `@fluojs/validation` to derive request schemas from DTO binding and validation metadata. Response DTOs become OpenAPI components only when they are referenced explicitly, such as with `@ApiResponse(..., { type: ResponseDto })` or `extraModels`.
 
+### OpenAPI 3.1 Exclusive Bounds
+`OpenApiSchemaObject` accepts OpenAPI 3.1 numeric `exclusiveMinimum` and `exclusiveMaximum` values while retaining compatibility with legacy boolean metadata. A `true` flag paired with `minimum` or `maximum` becomes the corresponding numeric exclusive bound in the emitted document, and a `false` flag is omitted while its inclusive bound remains. Finite numeric exclusive bounds pass through unchanged. A `true` flag without a finite paired bound, or a non-finite numeric exclusive bound, fails document generation instead of emitting an invalid OpenAPI 3.1 schema. The same normalization runs after `documentTransform` before the document is exposed.
+
+### OpenAPI 3.1 Nullable Schemas
+`OpenApiSchemaObject` continues to accept the legacy boolean `nullable` keyword as compatibility input, but generated OpenAPI 3.1 documents never emit it. `nullable: true` adds `null` to a declared `type` union while preserving scalar and array constraints; schemas without `type`, including `$ref` schemas, become an `anyOf` union with `{ type: 'null' }`. `nullable: false` is removed without changing the schema. Existing null unions are not duplicated, and the recursive normalization also runs after `documentTransform`.
+
 ### Versioning Support
 Handles URI-based versioning from `@fluojs/http` automatically. Your OpenAPI paths will correctly reflect the resolved versioned routes.
 
 ### Security Documentation
-Easily document authentication requirements like Bearer tokens or API keys using `@ApiBearerAuth()` and `@ApiSecurity()`.
+Easily document authentication requirements like Bearer tokens or API keys using `@ApiBearerAuth()` and `@ApiSecurity(name, scopes?)`.
 
-Stacking multiple `@ApiSecurity()` decorators for the same scheme merges scopes into one cumulative OpenAPI security requirement for that scheme. This keeps OAuth-style requirements deterministic when a route declares overlapping scopes such as `['reports:read']` and `['reports:write', 'reports:read']`, while different schemes remain separate requirements.
+Stacking multiple `@ApiSecurity(name, scopes?)` decorators for the same scheme merges scopes into one cumulative OpenAPI security requirement for that scheme. This keeps OAuth-style requirements deterministic when a route declares overlapping scopes such as `['reports:read']` and `['reports:write', 'reports:read']`, while different schemes remain separate requirements.
 
 ### Deterministic Swagger UI Assets
 When `ui: true` is enabled, the generated `/docs` page references an exact `swagger-ui-dist` asset version so release behavior stays deterministic across package updates. If your deployment requires self-hosted assets for offline or CSP-controlled environments, set `swaggerUiAssets.cssUrl` and `swaggerUiAssets.jsBundleUrl`; the generated HTML escapes those URLs and does not expose the Swagger UI instance on `window.ui`.
@@ -135,6 +162,13 @@ Paths follow the `@fluojs/http` route grammar and normalize duplicate or trailin
 ### Async Registration and Options
 Use `OpenApiModule.forRootAsync(...)` when title/version/source configuration comes from DI or async setup. Put registration-time `documentPath` and `uiPath` beside `inject` and `useFactory`; return `sources`, `descriptors`, `securitySchemes`, `extraModels`, `defaultErrorResponsesPolicy`, `documentTransform`, `ui`, and `swaggerUiAssets` from the factory. `defaultErrorResponsesPolicy` defaults to injecting standard error responses and an `ErrorResponse` schema, while `documentTransform` runs after document generation and before serving.
 
+### NestJS Migration Contract Differences
+Generated documents are not a one-to-one NestJS Swagger compatibility layer. By default, fluo adds `400`, `401`, `403`, `404`, and `500` responses that do not replace explicitly declared responses, and includes the shared `ErrorResponse` schema. Verify the generated error contract before regenerating clients; set `defaultErrorResponsesPolicy: 'omit'` when the legacy document must not receive those default responses.
+
+Fluo derives each `operationId` deterministically from the controller tag, handler name, HTTP method, and normalized path. Collisions receive numeric suffixes. If generated clients rely on legacy identifiers, rename the generated operation IDs in `documentTransform` before the document is served, then verify the transformed document with the client generator.
+
+With `forRootAsync(...)`, `documentPath` and `uiPath` are outer registration options because their routes are compiled before `useFactory(...)` resolves. Keep those paths beside `inject` and `useFactory`; return only document configuration from the factory. A path returned by the factory cannot reconfigure the already-registered routes.
+
 ## Public API
 
 - `OpenApiModule`: Main entry point for OpenAPI integration.
@@ -142,12 +176,13 @@ Use `OpenApiModule.forRootAsync(...)` when title/version/source configuration co
 - `ApiBody`, `ApiParam`, `ApiQuery`, `ApiHeader`, `ApiCookie`: Explicit request-body and parameter documentation decorators that override inferred request documentation when names overlap.
 - `ApiBearerAuth`, `ApiSecurity`: Security requirement decorators.
 - `ApiExcludeEndpoint`: Omit specific handlers from documentation.
+- `ApiOperationOptions`, `ApiResponseOptions`, `ApiParameterOptions`, `ApiBodyOptions`: Decorator option types accepted by `@ApiOperation(...)`, `@ApiResponse(...)`, `@ApiParam(...)`, `@ApiQuery(...)`, `@ApiHeader(...)`, `@ApiCookie(...)`, and `@ApiBody(...)`.
 - `buildOpenApiDocument`: Programmatic document builder (low-level).
 - `OpenApiHandlerRegistry`: Mutable descriptor registry used by advanced integrations to snapshot handler descriptors before document generation.
 - `getControllerTags`, `getMethodApiMetadata`: Metadata readers for advanced tests and integration tooling.
 - `OpenApiModuleOptions`, `OpenApiAsyncModuleOptions`, `OpenApiRouteOptions`, `OpenApiSwaggerUiAssetsOptions`, `BuildOpenApiDocumentOptions`, `DefaultErrorResponsesPolicy`: Option types for module and builder integrations.
 - `OpenApiDocument`, `OpenApiSecuritySchemeObject`, and related OpenAPI shape types: Typed document surface for tests, tooling, and integrations.
-- `OpenApiSchemaObject`: Typed schema surface for explicit `@ApiBody(...)` and `@ApiResponse(...)` schemas, including OpenAPI 3.1 composition (`allOf`, `oneOf`, `anyOf`), object/array constraints, examples/defaults, and read/write/deprecated annotations.
+- `OpenApiSchemaObject`: Typed schema surface for explicit `@ApiBody(...)` and `@ApiResponse(...)` schemas, including OpenAPI 3.1 composition (`allOf`, `oneOf`, `anyOf`), null unions with legacy `nullable` input compatibility, object/array constraints, examples/defaults, and read/write/deprecated annotations.
 
 ## Related Packages
 

package/dist/decorators.d.ts

@@ -121,10 +121,11 @@ export declare function ApiTag(tag: string): ClassDecoratorFn;
 /**
  * Describe a controller method's OpenAPI operation metadata.
  *
- * @param options Operation metadata such as summary, description, and deprecation flag.
+ * @param options Operation metadata; omission or `undefined` uses `{}` without inventing operation fields.
  * @returns A method decorator that stores operation metadata.
+ * @remarks An empty write can overwrite earlier stacked operation metadata; it is not equivalent to omitting the decorator.
  */
-export declare function ApiOperation(options: ApiOperationOptions): MethodDecoratorFn;
+export declare function ApiOperation(options?: ApiOperationOptions): MethodDecoratorFn;
 /**
  * Exclude a controller method from generated OpenAPI `paths`.
  *
@@ -174,10 +175,11 @@ export declare function ApiCookie(name: string, options?: ApiParameterOptions):
 /**
  * Declare an explicit request body for a controller method.
  *
- * @param options Request-body metadata and schema/content declarations.
+ * @param options Request-body metadata; omission or `undefined` uses `{}` without inventing a schema or required flag.
  * @returns A method decorator that stores request-body metadata.
+ * @remarks Empty metadata preserves DTO body inference and emits no body without inference. It can overwrite earlier stacked body metadata.
  */
-export declare function ApiBody(options: ApiBodyOptions): MethodDecoratorFn;
+export declare function ApiBody(options?: ApiBodyOptions): MethodDecoratorFn;
 /**
  *  Declare an expected HTTP response for a controller method.
  *

package/dist/decorators.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"decorators.d.ts","sourceRoot":"","sources":["../src/decorators.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"decorators.d.ts","sourceRoot":"","sources":["../src/decorators.ts"],"names":[],"mappings":"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"}

package/dist/decorators.js

@@ -186,10 +186,11 @@ export function ApiTag(tag) {
 /**
  * Describe a controller method's OpenAPI operation metadata.
  *
- * @param options Operation metadata such as summary, description, and deprecation flag.
+ * @param options Operation metadata; omission or `undefined` uses `{}` without inventing operation fields.
  * @returns A method decorator that stores operation metadata.
+ * @remarks An empty write can overwrite earlier stacked operation metadata; it is not equivalent to omitting the decorator.
  */
-export function ApiOperation(options) {
+export function ApiOperation(options = {}) {
   return (_value, context) => {
     const bag = context.metadata;
     let map = bag[openApiMethodOperationKey];
@@ -336,10 +337,11 @@ export function ApiCookie(name, options = {}) {
 /**
  * Declare an explicit request body for a controller method.
  *
- * @param options Request-body metadata and schema/content declarations.
+ * @param options Request-body metadata; omission or `undefined` uses `{}` without inventing a schema or required flag.
  * @returns A method decorator that stores request-body metadata.
+ * @remarks Empty metadata preserves DTO body inference and emits no body without inference. It can overwrite earlier stacked body metadata.
  */
-export function ApiBody(options) {
+export function ApiBody(options = {}) {
   return (_value, context) => {
     const bag = context.metadata;
     let map = bag[openApiMethodRequestBodyKey];

package/dist/openapi-module.js

@@ -161,9 +161,9 @@ export class OpenApiModule {
         } = _applyDecs(this, [Controller(''), Inject(openApiDocumentToken, openApiModuleOptionsToken)], [[Get(routes.documentPath), 2, "getDocument"], [Get(routes.uiPath), 2, "getSwaggerUi"]]));
       }
       constructor(document, options) {
+        _initProto(this);
         this.document = document;
         this.options = options;
-        _initProto(this);
       }
       getDocument() {
         return cloneSnapshotValue(this.document);

package/dist/path-item.d.ts

@@ -0,0 +1,62 @@
+import type { OpenApiOperationObject, OpenApiParameterObject } from './schema-builder.js';
+/** Standard OpenAPI 3.1 operation keys accepted on a Path Item Object. */
+export type OpenApiOperationMethod = 'delete' | 'get' | 'head' | 'options' | 'patch' | 'post' | 'put' | 'trace';
+interface OpenApiReferenceObject {
+    $ref: string;
+    summary?: string;
+    description?: string;
+}
+interface OpenApiServerObject {
+    url: string;
+    description?: string;
+    variables?: Record<string, {
+        default: string;
+        description?: string;
+        enum?: string[];
+    }>;
+}
+/**
+ * OpenAPI Path Item Object containing standard operations, fixed fields, and specification extensions.
+ */
+export interface OpenApiPathItemObject {
+    $ref?: string;
+    summary?: string;
+    description?: string;
+    servers?: OpenApiServerObject[];
+    parameters?: (OpenApiParameterObject | OpenApiReferenceObject)[];
+    delete?: OpenApiOperationObject;
+    get?: OpenApiOperationObject;
+    head?: OpenApiOperationObject;
+    options?: OpenApiOperationObject;
+    patch?: OpenApiOperationObject;
+    post?: OpenApiOperationObject;
+    put?: OpenApiOperationObject;
+    trace?: OpenApiOperationObject;
+    [extension: `x-${string}`]: unknown;
+}
+/**
+ * Resolve one Fluo descriptor method to its standard OpenAPI operation key.
+ *
+ * @param method Descriptor method supplied by HTTP route metadata.
+ * @param path OpenAPI path used to identify invalid descriptor input.
+ * @returns The corresponding standard OpenAPI operation key.
+ * @throws {TypeError} When Fluo cannot author the descriptor method as an OpenAPI operation.
+ */
+export declare function resolveDescriptorOperationMethod(method: string, path: string): OpenApiOperationMethod;
+/**
+ * Determine whether a Path Item key is a standard OpenAPI 3.1 operation.
+ *
+ * @param key Path Item key to inspect.
+ * @returns Whether the key is a standard operation key.
+ */
+export declare function isOpenApiOperationMethod(key: string): key is OpenApiOperationMethod;
+/**
+ * Validate every transformed Path Item against the OpenAPI 3.1 key policy.
+ *
+ * @param paths Final document paths after any caller transform.
+ * @returns Nothing when every Path Item key is valid.
+ * @throws {TypeError} When a Path Item contains an unknown non-extension key.
+ */
+export declare function validateOpenApiPathItemKeys(paths: Readonly<Record<string, object>>): void;
+export {};
+//# sourceMappingURL=path-item.d.ts.map

package/dist/path-item.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-item.d.ts","sourceRoot":"","sources":["../src/path-item.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAE1F,0EAA0E;AAC1E,MAAM,MAAM,sBAAsB,GAAG,QAAQ,GAAG,KAAK,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,CAAC;AAEhH,UAAU,sBAAsB;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,UAAU,mBAAmB;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QACzB,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;KACjB,CAAC,CAAC;CACJ;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,mBAAmB,EAAE,CAAC;IAChC,UAAU,CAAC,EAAE,CAAC,sBAAsB,GAAG,sBAAsB,CAAC,EAAE,CAAC;IACjE,MAAM,CAAC,EAAE,sBAAsB,CAAC;IAChC,GAAG,CAAC,EAAE,sBAAsB,CAAC;IAC7B,IAAI,CAAC,EAAE,sBAAsB,CAAC;IAC9B,OAAO,CAAC,EAAE,sBAAsB,CAAC;IACjC,KAAK,CAAC,EAAE,sBAAsB,CAAC;IAC/B,IAAI,CAAC,EAAE,sBAAsB,CAAC;IAC9B,GAAG,CAAC,EAAE,sBAAsB,CAAC;IAC7B,KAAK,CAAC,EAAE,sBAAsB,CAAC;IAC/B,CAAC,SAAS,EAAE,KAAK,MAAM,EAAE,GAAG,OAAO,CAAC;CACrC;AAyBD;;;;;;;GAOG;AACH,wBAAgB,gCAAgC,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,sBAAsB,CAOrG;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,IAAI,sBAAsB,CAEnF;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,IAAI,CAUzF"}

package/dist/path-item.js

@@ -0,0 +1,53 @@
+/** Standard OpenAPI 3.1 operation keys accepted on a Path Item Object. */
+
+/**
+ * OpenAPI Path Item Object containing standard operations, fixed fields, and specification extensions.
+ */
+
+const OPENAPI_PATH_ITEM_FIXED_FIELDS = new Set(['$ref', 'description', 'parameters', 'servers', 'summary']);
+const DESCRIPTOR_OPERATION_METHODS = new Map([['DELETE', 'delete'], ['GET', 'get'], ['HEAD', 'head'], ['OPTIONS', 'options'], ['PATCH', 'patch'], ['POST', 'post'], ['PUT', 'put'], ['TRACE', 'trace']]);
+const OPENAPI_OPERATION_METHODS = new Set([...DESCRIPTOR_OPERATION_METHODS.values()]);
+
+/**
+ * Resolve one Fluo descriptor method to its standard OpenAPI operation key.
+ *
+ * @param method Descriptor method supplied by HTTP route metadata.
+ * @param path OpenAPI path used to identify invalid descriptor input.
+ * @returns The corresponding standard OpenAPI operation key.
+ * @throws {TypeError} When Fluo cannot author the descriptor method as an OpenAPI operation.
+ */
+export function resolveDescriptorOperationMethod(method, path) {
+  const operationMethod = DESCRIPTOR_OPERATION_METHODS.get(method);
+  if (operationMethod !== undefined) {
+    return operationMethod;
+  }
+  throw new TypeError(`OpenAPI cannot document unsupported HTTP method "${method}" for path "${path}".`);
+}
+
+/**
+ * Determine whether a Path Item key is a standard OpenAPI 3.1 operation.
+ *
+ * @param key Path Item key to inspect.
+ * @returns Whether the key is a standard operation key.
+ */
+export function isOpenApiOperationMethod(key) {
+  return OPENAPI_OPERATION_METHODS.has(key);
+}
+
+/**
+ * Validate every transformed Path Item against the OpenAPI 3.1 key policy.
+ *
+ * @param paths Final document paths after any caller transform.
+ * @returns Nothing when every Path Item key is valid.
+ * @throws {TypeError} When a Path Item contains an unknown non-extension key.
+ */
+export function validateOpenApiPathItemKeys(paths) {
+  for (const [path, pathItem] of Object.entries(paths)) {
+    for (const key of Object.keys(pathItem)) {
+      if (isOpenApiOperationMethod(key) || OPENAPI_PATH_ITEM_FIXED_FIELDS.has(key) || key.startsWith('x-')) {
+        continue;
+      }
+      throw new TypeError(`OpenAPI Path Item for path "${path}" contains unsupported key "${key}".`);
+    }
+  }
+}

package/dist/schema-bounds.d.ts

@@ -0,0 +1,9 @@
+import type { OpenApiDocument } from './schema-builder.js';
+/**
+ * Normalize legacy exclusive-bound and nullable metadata before an OpenAPI 3.1 document is exposed.
+ *
+ * @param document Generated document, including any final caller transform.
+ * @returns A detached document whose schema keywords use OpenAPI 3.1 forms.
+ */
+export declare function normalizeOpenApiDocumentSchemaBounds(document: OpenApiDocument): OpenApiDocument;
+//# sourceMappingURL=schema-bounds.d.ts.map

package/dist/schema-bounds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-bounds.d.ts","sourceRoot":"","sources":["../src/schema-bounds.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,eAAe,EAMhB,MAAM,qBAAqB,CAAC;AAuP7B;;;;;GAKG;AACH,wBAAgB,oCAAoC,CAAC,QAAQ,EAAE,eAAe,GAAG,eAAe,CAiB/F"}

package/dist/schema-bounds.js

@@ -0,0 +1,175 @@
+import { isOpenApiOperationMethod } from './path-item.js';
+function normalizeSchemaRecord(schemas, path, normalizedSchemas) {
+  const normalized = {};
+  for (const [name, schema] of Object.entries(schemas)) {
+    normalized[name] = normalizeOpenApiSchemaBounds(schema, `${path}.${name}`, normalizedSchemas);
+  }
+  return normalized;
+}
+function normalizeSchemaList(schemas, path, normalizedSchemas) {
+  return schemas.map((schema, index) => normalizeOpenApiSchemaBounds(schema, `${path}[${String(index)}]`, normalizedSchemas));
+}
+function normalizeOpenApiSchemaBounds(schema, path, normalizedSchemas) {
+  const cachedSchema = normalizedSchemas.get(schema);
+  if (cachedSchema) {
+    return cachedSchema;
+  }
+  if (schema.nullable === true && schema.type === undefined) {
+    const nullableUnion = {};
+    const nonNullableSchema = {
+      ...schema
+    };
+    delete nonNullableSchema.nullable;
+    normalizedSchemas.set(schema, nullableUnion);
+    nullableUnion.anyOf = [normalizeOpenApiSchemaBounds(nonNullableSchema, `${path}.anyOf[0]`, normalizedSchemas), {
+      type: 'null'
+    }];
+    return nullableUnion;
+  }
+  const normalized = {
+    ...schema
+  };
+  normalizedSchemas.set(schema, normalized);
+  if (typeof schema.nullable === 'boolean') {
+    delete normalized.nullable;
+  }
+  if (schema.nullable === true && schema.type !== undefined) {
+    normalized.type = typeof schema.type === 'string' ? schema.type === 'null' ? 'null' : [schema.type, 'null'] : schema.type.includes('null') ? schema.type : [...schema.type, 'null'];
+  }
+  if (typeof schema.exclusiveMinimum === 'number' && !Number.isFinite(schema.exclusiveMinimum)) {
+    throw new TypeError(`OpenAPI schema ${path}.exclusiveMinimum must be a finite number.`);
+  }
+  if (typeof schema.exclusiveMinimum === 'boolean') {
+    delete normalized.exclusiveMinimum;
+    if (schema.exclusiveMinimum) {
+      if (schema.minimum === undefined || !Number.isFinite(schema.minimum)) {
+        throw new TypeError(`OpenAPI schema ${path}.exclusiveMinimum requires a finite minimum.`);
+      }
+      normalized.exclusiveMinimum = schema.minimum;
+      delete normalized.minimum;
+    }
+  }
+  if (typeof schema.exclusiveMaximum === 'number' && !Number.isFinite(schema.exclusiveMaximum)) {
+    throw new TypeError(`OpenAPI schema ${path}.exclusiveMaximum must be a finite number.`);
+  }
+  if (typeof schema.exclusiveMaximum === 'boolean') {
+    delete normalized.exclusiveMaximum;
+    if (schema.exclusiveMaximum) {
+      if (schema.maximum === undefined || !Number.isFinite(schema.maximum)) {
+        throw new TypeError(`OpenAPI schema ${path}.exclusiveMaximum requires a finite maximum.`);
+      }
+      normalized.exclusiveMaximum = schema.maximum;
+      delete normalized.maximum;
+    }
+  }
+  if (schema.allOf) {
+    normalized.allOf = normalizeSchemaList(schema.allOf, `${path}.allOf`, normalizedSchemas);
+  }
+  if (schema.oneOf) {
+    normalized.oneOf = normalizeSchemaList(schema.oneOf, `${path}.oneOf`, normalizedSchemas);
+  }
+  if (schema.anyOf) {
+    normalized.anyOf = normalizeSchemaList(schema.anyOf, `${path}.anyOf`, normalizedSchemas);
+  }
+  if (schema.not) {
+    normalized.not = normalizeOpenApiSchemaBounds(schema.not, `${path}.not`, normalizedSchemas);
+  }
+  if (schema.properties) {
+    normalized.properties = normalizeSchemaRecord(schema.properties, `${path}.properties`, normalizedSchemas);
+  }
+  if (schema.items) {
+    normalized.items = normalizeOpenApiSchemaBounds(schema.items, `${path}.items`, normalizedSchemas);
+  }
+  if (typeof schema.additionalProperties === 'object') {
+    normalized.additionalProperties = normalizeOpenApiSchemaBounds(schema.additionalProperties, `${path}.additionalProperties`, normalizedSchemas);
+  }
+  return normalized;
+}
+function normalizeContent(content, path, normalizedSchemas) {
+  const normalized = {};
+  for (const [mediaType, media] of Object.entries(content)) {
+    normalized[mediaType] = {
+      ...media,
+      schema: normalizeOpenApiSchemaBounds(media.schema, `${path}.${mediaType}.schema`, normalizedSchemas)
+    };
+  }
+  return normalized;
+}
+function normalizeResponses(responses, path, normalizedSchemas) {
+  const normalized = {};
+  for (const [status, response] of Object.entries(responses)) {
+    normalized[status] = {
+      ...response,
+      ...(response.content ? {
+        content: normalizeContent(response.content, `${path}.${status}.content`, normalizedSchemas)
+      } : {})
+    };
+  }
+  return normalized;
+}
+function normalizeOperation(operation, path, normalizedSchemas) {
+  return {
+    ...operation,
+    ...(operation.parameters ? {
+      parameters: operation.parameters.map((parameter, index) => ({
+        ...parameter,
+        schema: normalizeOpenApiSchemaBounds(parameter.schema, `${path}.parameters[${String(index)}].schema`, normalizedSchemas)
+      }))
+    } : {}),
+    ...(operation.requestBody ? {
+      requestBody: {
+        ...operation.requestBody,
+        content: normalizeContent(operation.requestBody.content, `${path}.requestBody.content`, normalizedSchemas)
+      }
+    } : {}),
+    responses: normalizeResponses(operation.responses, `${path}.responses`, normalizedSchemas)
+  };
+}
+function normalizePaths(paths, normalizedSchemas) {
+  const normalizedPaths = {};
+  for (const [path, pathItem] of Object.entries(paths)) {
+    const normalizedPathItem = {};
+    if (pathItem.parameters) {
+      normalizedPathItem.parameters = pathItem.parameters.map((parameter, index) => 'schema' in parameter ? {
+        ...parameter,
+        schema: normalizeOpenApiSchemaBounds(parameter.schema, `paths.${path}.parameters[${String(index)}].schema`, normalizedSchemas)
+      } : {
+        ...parameter
+      });
+    }
+    for (const [key, value] of Object.entries(pathItem)) {
+      if (key === 'parameters') {
+        continue;
+      }
+      if (isOpenApiOperationMethod(key)) {
+        normalizedPathItem[key] = value ? normalizeOperation(value, `paths.${path}.${key}`, normalizedSchemas) : undefined;
+        continue;
+      }
+      Reflect.set(normalizedPathItem, key, value);
+    }
+    normalizedPaths[path] = normalizedPathItem;
+  }
+  return normalizedPaths;
+}
+
+/**
+ * Normalize legacy exclusive-bound and nullable metadata before an OpenAPI 3.1 document is exposed.
+ *
+ * @param document Generated document, including any final caller transform.
+ * @returns A detached document whose schema keywords use OpenAPI 3.1 forms.
+ */
+export function normalizeOpenApiDocumentSchemaBounds(document) {
+  const normalizedSchemas = new WeakMap();
+  return {
+    ...document,
+    ...(document.components ? {
+      components: {
+        ...document.components,
+        ...(document.components.schemas ? {
+          schemas: normalizeSchemaRecord(document.components.schemas, 'components.schemas', normalizedSchemas)
+        } : {})
+      }
+    } : {}),
+    paths: normalizePaths(document.paths, normalizedSchemas)
+  };
+}

package/dist/schema-builder.d.ts

@@ -1,5 +1,7 @@
 import type { Constructor } from '@fluojs/core';
 import type { HandlerDescriptor } from '@fluojs/http';
+import { type OpenApiPathItemObject } from './path-item.js';
+export type { OpenApiPathItemObject } from './path-item.js';
 /**
  * JSON Schema primitive type names accepted by OpenAPI 3.1 schema objects.
  */
@@ -52,6 +54,7 @@ export interface OpenApiSchemaObject {
     deprecated?: boolean;
     readOnly?: boolean;
     writeOnly?: boolean;
+    /** Legacy compatibility input normalized to an OpenAPI 3.1 null union before emission. */
     nullable?: boolean;
     minimum?: number;
     maximum?: number;
@@ -147,12 +150,6 @@ export interface OpenApiOperationObject {
     requestBody?: OpenApiRequestBodyObject;
     security?: OpenApiSecurityRequirementObject[];
 }
-/**
- * OpenAPI path-item object containing one or more HTTP method operations.
- */
-export interface OpenApiPathItemObject {
-    [method: string]: OpenApiOperationObject | undefined;
-}
 /**
  * Root OpenAPI 3.1.0 document produced by `buildOpenApiDocument(...)`.
  */

package/dist/schema-builder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema-builder.d.ts","sourceRoot":"","sources":["../src/schema-builder.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"schema-builder.d.ts","sourceRoot":"","sources":["../src/schema-builder.ts"],"names":[],"mappings":"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"}

package/dist/schema-builder.js

@@ -1,5 +1,7 @@
 import { getDtoBindingSchema, getDtoValidationSchema } from '@fluojs/core/request-pipeline';
 import { getControllerTags, getMethodApiMetadata } from './decorators.js';
+import { resolveDescriptorOperationMethod, validateOpenApiPathItemKeys } from './path-item.js';
+import { normalizeOpenApiDocumentSchemaBounds } from './schema-bounds.js';
 import { cloneSnapshotValue } from './snapshot.js';
 
 /**
@@ -46,10 +48,6 @@ import { cloneSnapshotValue } from './snapshot.js';
  * OpenAPI operation object emitted for a single HTTP method on a path.
  */
 
-/**
- * OpenAPI path-item object containing one or more HTTP method operations.
- */
-
 /**
  * Root OpenAPI 3.1.0 document produced by `buildOpenApiDocument(...)`.
  */
@@ -491,12 +489,9 @@ function ensureComponentSchema(dto, componentSchemas, context) {
   const schemaName = getDtoSchemaName(dto, context);
   return ensureComponentSchemaFromEntries(schemaName, collectDtoEntries(dto, context), componentSchemas, context);
 }
-function createParameters(dto, context) {
-  if (!dto) {
-    return [];
-  }
-  const entries = collectDtoEntries(dto, context).filter(entry => entry.binding?.metadata.source === 'path' || entry.binding?.metadata.source === 'query' || entry.binding?.metadata.source === 'header' || entry.binding?.metadata.source === 'cookie');
-  return entries.map(entry => {
+function createParameters(dto, routePath, context) {
+  const entries = dto ? collectDtoEntries(dto, context).filter(entry => entry.binding?.metadata.source === 'path' || entry.binding?.metadata.source === 'query' || entry.binding?.metadata.source === 'header' || entry.binding?.metadata.source === 'cookie') : [];
+  const parameters = entries.map(entry => {
     const source = entry.binding.metadata.source;
     const rules = entry.validation?.rules ?? [];
     const inferred = inferPrimitiveTypeFromRules(rules, context) ?? {};
@@ -509,6 +504,22 @@ function createParameters(dto, context) {
       schema
     };
   });
+  const documentedPathParameters = new Set(parameters.filter(parameter => parameter.in === 'path').map(parameter => parameter.name));
+  for (const match of routePath.matchAll(/:([a-zA-Z_][a-zA-Z0-9_]*)/g)) {
+    const name = match[1];
+    if (!documentedPathParameters.has(name)) {
+      documentedPathParameters.add(name);
+      parameters.push({
+        in: 'path',
+        name,
+        required: true,
+        schema: {
+          type: 'string'
+        }
+      });
+    }
+  }
+  return parameters;
 }
 function ensureErrorResponseSchema(componentSchemas) {
   const schemaName = 'ErrorResponse';
@@ -785,7 +796,7 @@ function hasBearerAuthRequirement(security) {
   return Boolean(security?.some(requirement => Object.keys(requirement).includes('bearerAuth')));
 }
 function createOperationObject(descriptor, methodMeta, responses, componentSchemas, security, context, usedOperationIds) {
-  const parameters = mergeOperationParameters(createParameters(descriptor.route.request, context), methodMeta?.parameters);
+  const parameters = mergeOperationParameters(createParameters(descriptor.route.request, descriptor.route.path, context), methodMeta?.parameters);
   const requestBody = mergeOperationRequestBody(createRequestBody(descriptor.route.request, componentSchemas, context), methodMeta);
   return {
     operationId: resolveUniqueOperationId(normalizeOperationId(descriptor), usedOperationIds),
@@ -813,11 +824,11 @@ function createOperationObject(descriptor, methodMeta, responses, componentSchem
 }
 function buildOperationEntry(descriptor, componentSchemas, defaultErrorResponsesPolicy, context, usedOperationIds) {
   const openApiPath = expressPathToOpenApi(descriptor.route.path);
-  const method = descriptor.route.method.toLowerCase();
   const methodMeta = getMethodApiMetadata(descriptor.controllerToken, descriptor.methodName);
   if (methodMeta?.excludeEndpoint === true) {
     return undefined;
   }
+  const method = resolveDescriptorOperationMethod(descriptor.route.method, openApiPath);
   const responses = createOperationResponses(descriptor, methodMeta, componentSchemas, defaultErrorResponsesPolicy, context);
   const security = createOperationSecurity(methodMeta);
   const operation = createOperationObject(descriptor, methodMeta, responses, componentSchemas, security, context, usedOperationIds);
@@ -917,5 +928,7 @@ export function buildOpenApiDocument(options) {
     openapi: '3.1.0',
     paths
   };
-  return options.documentTransform ? options.documentTransform(document) : document;
+  const transformedDocument = options.documentTransform ? options.documentTransform(document) : document;
+  validateOpenApiPathItemKeys(transformedDocument.paths);
+  return normalizeOpenApiDocumentSchemaBounds(transformedDocument);
 }

package/package.json

@@ -9,7 +9,7 @@
     "documentation",
     "rest"
   ],
-  "version": "1.1.0",
+  "version": "2.0.0",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -18,7 +18,7 @@
     "directory": "packages/openapi"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=24.0.0 <27"
   },
   "publishConfig": {
     "access": "public"
@@ -36,13 +36,14 @@
     "dist"
   ],
   "dependencies": {
-    "@fluojs/core": "^1.1.0",
-    "@fluojs/http": "^2.0.1",
-    "@fluojs/runtime": "^2.0.1",
-    "@fluojs/validation": "^1.0.6"
+    "@fluojs/core": "^2.0.0",
+    "@fluojs/http": "^3.0.0",
+    "@fluojs/runtime": "^3.0.0"
   },
   "devDependencies": {
-    "vitest": "^3.2.4"
+    "vitest": "^4.1.11",
+    "@fluojs/platform-nodejs": "^2.0.0",
+    "@fluojs/validation": "^2.0.0"
   },
   "scripts": {
     "prebuild": "node ../../tooling/scripts/clean-dist.mjs",