@fluojs/openapi 1.0.3 → 1.1.0

package/README.ko.md

@@ -2,7 +2,7 @@
 
 <p><a href="./README.md"><kbd>English</kbd></a> <strong><kbd>한국어</kbd></strong></p>
 
-fluo를 위한 데코레이터 기반 OpenAPI 3.1.0 문서 생성 패키지입니다. 별도의 수동 동기화 없이 API 문서를 자동으로 생성하고 제공하며, 선택적으로 Swagger UI를 지원합니다.
+fluo를 위한 descriptor-driven OpenAPI 3.1.0 문서 생성 패키지입니다. 명시적 문서 metadata를 위한 standard decorator와 선택적 Swagger UI를 지원합니다.
 
 ## 목차
 
@@ -25,7 +25,8 @@ pnpm add @fluojs/openapi
 - **Swagger UI**를 사용하여 REST API에 대한 대화형 문서를 제공하고 싶을 때.
 - 클라이언트 생성 또는 테스트를 위해 기계 읽기 가능한 **OpenAPI 3.1.0** 명세가 필요할 때.
 - 표준 데코레이터를 사용하여 API 문서와 코드를 동기화된 상태로 유지하고 싶을 때.
-- DTO 및 검증 메타데이터를 사용하여 복잡한 요청/응답 모델을 문서화해야 할 때.
+- DTO binding/validation metadata에서 request model을 파생하고 response model을 명시적으로 선언해야 할 때.
+- 하나의 application에서 여러 API version 또는 audience를 위해 JSON/UI route를 분리해야 할 때.
 
 ## 빠른 시작
 
@@ -74,7 +75,7 @@ await app.listen(3000);
 ## 핵심 기능
 
 ### 자동 명세 생성
-fluo는 컨트롤러와 메서드를 조사하여 전체 OpenAPI 3.1.0 문서를 작성합니다. 여기에는 경로, 메서드, 파라미터 및 요청 바디가 포함됩니다.
+fluo는 `sources`와 `descriptors`로 전달된 controller 및 handler descriptor만 조사하여 OpenAPI 3.1.0 문서를 작성합니다. 이 명시적 입력 집합의 경로, 메서드, 파라미터, 요청 바디가 포함되며, controller를 application module에 import하는 것만으로는 자동 추가되지 않습니다.
 
 ### 응답 미디어 타입
 HTTP 핸들러가 `@fluojs/http`의 `@Produces(...)`를 선언하면, 생성된 OpenAPI 응답은 해당 미디어 타입을 response `content` 키로 사용합니다. 예를 들어 `@ApiResponse(...)` 스키마가 있는 핸들러에 `@Produces('application/json', 'application/problem+json')`를 붙이면, `application/json`만으로 되돌아가지 않고 두 미디어 타입 모두 같은 응답 스키마로 방출합니다.
@@ -82,8 +83,11 @@ HTTP 핸들러가 `@fluojs/http`의 `@Produces(...)`를 선언하면, 생성된
 ### 기본 성공 응답
 핸들러가 `@ApiResponse(...)` 또는 `@HttpCode(...)`를 선언하지 않으면 OpenAPI builder는 메서드만 기준으로 한 암묵적 기본값을 적용합니다. `POST` 핸들러는 기본적으로 `201`, 그 밖의 메서드는 `200`을 사용합니다. `DELETE`와 `OPTIONS`처럼 본문이 없거나 런타임 결과에 따라 달라질 수 있는 경우에는 `@HttpCode(...)` 또는 `@ApiResponse(...)`로 의도한 성공 상태를 명시하세요.
 
+### 응답 문서화 경계
+Builder는 handler 반환값이나 TypeScript 반환 타입을 검사해 response content를 추론하지 않습니다. 기본 success response에는 status와 `OK` description만 포함됩니다. OpenAPI 문서에 response body를 설명해야 하면 `@ApiResponse(...)`에 `schema` 또는 `type`을 추가하세요. 둘 중 어느 것도 없으면 명시적 response도 status와 description만 포함합니다.
+
 ### 통합 DTO 스키마
-`@fluojs/validation`과 원활하게 작동합니다. DTO 클래스는 자동으로 OpenAPI 컴포넌트로 변환되어 적절한 오퍼레이션에서 참조됩니다.
+`@fluojs/validation`과 함께 DTO binding 및 validation metadata에서 request schema를 파생합니다. Response DTO는 `@ApiResponse(..., { type: ResponseDto })` 또는 `extraModels`처럼 명시적으로 참조할 때만 OpenAPI component가 됩니다.
 
 ### 버전 관리 지원
 `@fluojs/http`의 URI 기반 버전 관리를 자동으로 처리합니다. OpenAPI 경로에 해결된 버전 경로가 올바르게 반영됩니다.
@@ -96,11 +100,40 @@ HTTP 핸들러가 `@fluojs/http`의 `@Produces(...)`를 선언하면, 생성된
 ### 결정적인 Swagger UI 자산
 `ui: true`를 활성화하면 생성되는 `/docs` 페이지는 정확한 `swagger-ui-dist` 버전의 자산을 참조하여 패키지 릴리스마다 동일한 동작을 유지합니다. 오프라인 또는 CSP 제어 환경에서 자체 호스팅 자산이 필요하면 `swaggerUiAssets.cssUrl`과 `swaggerUiAssets.jsBundleUrl`을 설정하세요. 생성된 HTML은 해당 URL을 이스케이프하며 Swagger UI 인스턴스를 `window.ui`에 노출하지 않습니다.
 
+### 설정 가능한 문서 라우트
+각 `OpenApiModule` 등록은 `documentPath`에서 JSON을 제공하고 `uiPath`에 Swagger UI route를 예약합니다. 기본값은 계속 `/openapi.json`과 `/docs`이므로 기존 application은 설정을 바꿀 필요가 없습니다. 하나의 application에서 여러 OpenAPI module을 import할 때는 두 path를 모두 지정하세요.
+
+```typescript
+@Module({
+  imports: [
+    OpenApiModule.forRoot({
+      documentPath: '/openapi/public.json',
+      sources: [{ controllerToken: PublicController }],
+      title: 'Public API',
+      ui: true,
+      uiPath: '/docs/public',
+      version: '1.0.0',
+    }),
+    OpenApiModule.forRoot({
+      documentPath: '/openapi/admin.json',
+      sources: [{ controllerToken: AdminController }],
+      title: 'Admin API',
+      ui: true,
+      uiPath: '/docs/admin',
+      version: '1.0.0',
+    }),
+  ],
+})
+class AppModule {}
+```
+
+Path는 `@fluojs/http` route grammar를 따르며 중복 slash와 trailing slash를 정규화합니다. Route collision에는 document descriptor precedence가 적용되지 않습니다. JSON/UI path끼리, 서로 다른 OpenAPI module끼리, 또는 다른 application controller와 정규화된 `GET` route가 겹치면 application bootstrap이 `RouteConflictError`로 실패합니다. `ui`가 false여도 UI route는 예약되므로, 설정한 endpoint는 문서화된 `Swagger UI is disabled.` not-found response를 반환할 수 있습니다.
+
 ### 모듈 옵션 결정성
-`OpenApiModule.forRoot(...)`는 등록 시점에 옵션을 스냅샷하고 freeze합니다. 등록 후 원본 options 객체, `sources`, `descriptors`, `securitySchemes`, `extraModels`, `swaggerUiAssets`를 변경해도 제공되는 OpenAPI 문서나 `/docs` HTML은 바뀌지 않습니다. 생성된 singleton 문서도 defensive copy로 제공되므로 downstream response serialization이나 테스트가 이후 요청에 쓰이는 저장 문서를 변경할 수 없습니다. `OpenApiModule.forRootAsync(...)`도 async factory가 resolve된 뒤 같은 스냅샷을 적용하며, factory 실패는 bootstrap 중 전파됩니다.
+`OpenApiModule.forRoot(...)`는 등록 시점에 옵션을 스냅샷하고 freeze합니다. 등록 후 원본 options 객체, `documentPath`, `uiPath`, `sources`, `descriptors`, `securitySchemes`, `extraModels`, `swaggerUiAssets`를 변경해도 제공되는 OpenAPI 문서나 UI HTML은 바뀌지 않습니다. 생성된 singleton 문서도 defensive copy로 제공되므로 downstream response serialization이나 테스트가 이후 요청에 쓰이는 저장 문서를 변경할 수 없습니다. `OpenApiModule.forRootAsync(...)`는 module compile 전에 outer registration의 `documentPath`와 `uiPath`를 고정하고, async document-options factory가 resolve된 뒤 같은 스냅샷을 적용하며, factory 실패는 bootstrap 중 전파됩니다.
 
 ### Async 등록과 옵션
-title/version/source 설정이 DI나 async setup에서 나오는 경우 `OpenApiModule.forRootAsync(...)`를 사용합니다. Module option에는 `sources`, `descriptors`, `securitySchemes`, `extraModels`, `defaultErrorResponsesPolicy`, `documentTransform`, `ui`, `swaggerUiAssets`가 포함됩니다. `defaultErrorResponsesPolicy`는 기본적으로 표준 error response와 `ErrorResponse` schema를 주입하며, `documentTransform`은 문서 생성 뒤 제공되기 전에 실행됩니다.
+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`은 문서 생성 뒤 제공되기 전에 실행됩니다.
 
 ## 공개 API
 
@@ -112,7 +145,7 @@ title/version/source 설정이 DI나 async setup에서 나오는 경우 `OpenApi
 - `buildOpenApiDocument`: 프로그래밍 방식의 문서 빌더 (저수준).
 - `OpenApiHandlerRegistry`: 고급 통합에서 문서 생성 전에 handler descriptor를 스냅샷하는 mutable descriptor registry.
 - `getControllerTags`, `getMethodApiMetadata`: 고급 테스트와 통합 tooling을 위한 metadata reader.
-- `OpenApiModuleOptions`, `OpenApiSwaggerUiAssetsOptions`, `BuildOpenApiDocumentOptions`, `DefaultErrorResponsesPolicy`: module과 builder integration을 위한 option type.
+- `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 주석을 포함합니다.
 
@@ -125,4 +158,5 @@ title/version/source 설정이 DI나 async setup에서 나오는 경우 `OpenApi
 ## 예제 소스
 
 - `packages/openapi/src/openapi-module.test.ts`: 통합 테스트 및 사용 예제.
+- `packages/openapi/src/openapi-module-routes.test.ts`: 기본/custom/multi-document/route-collision 예제.
 - `packages/openapi/src/schema-builder.test.ts`: 문서 builder와 schema generation 예제.

package/README.md

@@ -2,7 +2,7 @@
 
 <p><strong><kbd>English</kbd></strong> <a href="./README.ko.md"><kbd>한국어</kbd></a></p>
 
-Decorator-based OpenAPI 3.1.0 document generation for fluo. Automatically generate and serve your API documentation with zero manual synchronization and optional Swagger UI support.
+Descriptor-driven OpenAPI 3.1.0 document generation for fluo, with standard decorators for explicit documentation metadata and optional Swagger UI support.
 
 ## Table of Contents
 
@@ -25,7 +25,8 @@ pnpm add @fluojs/openapi
 - When you want to provide interactive documentation for your REST API using **Swagger UI**.
 - When you need a machine-readable **OpenAPI 3.1.0** specification for client generation or testing.
 - When you want to keep your API documentation in sync with your code using standard decorators.
-- When you need to document complex request/response models using DTOs and validation metadata.
+- When you need to derive request models from DTO binding/validation metadata and declare response models explicitly.
+- When one application needs separate JSON and UI routes for multiple API versions or audiences.
 
 ## Quick Start
 
@@ -74,7 +75,7 @@ When a prebuilt descriptor and a discovered source resolve to the same OpenAPI p
 ## Core Capabilities
 
 ### Automated Specification Generation
-fluo inspects your controllers and methods to build a complete OpenAPI 3.1.0 document. This includes paths, methods, parameters, and request bodies.
+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.
 
 ### 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`.
@@ -82,8 +83,11 @@ When an HTTP handler declares `@Produces(...)` from `@fluojs/http`, generated Op
 ### Default Success Responses
 When a handler does not declare `@ApiResponse(...)` or `@HttpCode(...)`, the OpenAPI builder applies method-only implicit defaults: `POST` handlers default to `201`, and other methods default to `200`. Bodyless or runtime-dependent cases such as `DELETE` and `OPTIONS` should declare the intended success status explicitly with `@HttpCode(...)` or `@ApiResponse(...)`.
 
+### Response Documentation Boundary
+The builder does not inspect handler return values or TypeScript return types to infer response content. A default success response contains only its status and the description `OK`. Add `@ApiResponse(...)` with `schema` or `type` when the OpenAPI document must describe a response body; without either field, an explicit response still contains status and description only.
+
 ### Integrated DTO Schemas
-Works seamlessly with `@fluojs/validation`. Your DTO classes are automatically converted to OpenAPI components and referenced in the appropriate operations.
+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`.
 
 ### Versioning Support
 Handles URI-based versioning from `@fluojs/http` automatically. Your OpenAPI paths will correctly reflect the resolved versioned routes.
@@ -96,11 +100,40 @@ Stacking multiple `@ApiSecurity()` decorators for the same scheme merges scopes
 ### 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`.
 
+### Configurable Document Routes
+Each `OpenApiModule` registration serves JSON at `documentPath` and reserves its Swagger UI route at `uiPath`. The defaults remain `/openapi.json` and `/docs`, so existing applications do not need configuration changes. Set both paths when one application imports multiple OpenAPI modules:
+
+```typescript
+@Module({
+  imports: [
+    OpenApiModule.forRoot({
+      documentPath: '/openapi/public.json',
+      sources: [{ controllerToken: PublicController }],
+      title: 'Public API',
+      ui: true,
+      uiPath: '/docs/public',
+      version: '1.0.0',
+    }),
+    OpenApiModule.forRoot({
+      documentPath: '/openapi/admin.json',
+      sources: [{ controllerToken: AdminController }],
+      title: 'Admin API',
+      ui: true,
+      uiPath: '/docs/admin',
+      version: '1.0.0',
+    }),
+  ],
+})
+class AppModule {}
+```
+
+Paths follow the `@fluojs/http` route grammar and normalize duplicate or trailing slashes. Route collisions do not use document-descriptor precedence: if two normalized `GET` routes collide—between JSON and UI paths, separate OpenAPI modules, or another application controller—application bootstrap fails with `RouteConflictError`. The UI route remains reserved when `ui` is false so the configured endpoint can return the documented `Swagger UI is disabled.` not-found response.
+
 ### Module Option Determinism
-`OpenApiModule.forRoot(...)` snapshots and freezes its options at registration time. Mutating the original options object, `sources`, `descriptors`, `securitySchemes`, `extraModels`, or `swaggerUiAssets` after registration does not alter the served OpenAPI document or `/docs` HTML. The generated singleton document is also served through defensive copies, so downstream response serialization or tests cannot mutate the stored document for later requests. `OpenApiModule.forRootAsync(...)` applies the same snapshot once the async factory resolves, and factory failures propagate during bootstrap.
+`OpenApiModule.forRoot(...)` snapshots and freezes its options at registration time. Mutating the original options object, `documentPath`, `uiPath`, `sources`, `descriptors`, `securitySchemes`, `extraModels`, or `swaggerUiAssets` after registration does not alter the served OpenAPI document or UI HTML. The generated singleton document is also served through defensive copies, so downstream response serialization or tests cannot mutate the stored document for later requests. `OpenApiModule.forRootAsync(...)` fixes `documentPath` and `uiPath` from the outer registration before module compilation, applies the same snapshot once the async document-options factory resolves, and propagates factory failures during bootstrap.
 
 ### Async Registration and Options
-Use `OpenApiModule.forRootAsync(...)` when title/version/source configuration comes from DI or async setup. Module options include `sources`, `descriptors`, `securitySchemes`, `extraModels`, `defaultErrorResponsesPolicy`, `documentTransform`, `ui`, and `swaggerUiAssets`. `defaultErrorResponsesPolicy` defaults to injecting standard error responses and an `ErrorResponse` schema, while `documentTransform` runs after document generation and before serving.
+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.
 
 ## Public API
 
@@ -112,7 +145,7 @@ Use `OpenApiModule.forRootAsync(...)` when title/version/source configuration co
 - `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`, `OpenApiSwaggerUiAssetsOptions`, `BuildOpenApiDocumentOptions`, `DefaultErrorResponsesPolicy`: Option types for module and builder integrations.
+- `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.
 
@@ -125,4 +158,5 @@ Use `OpenApiModule.forRootAsync(...)` when title/version/source configuration co
 ## Example Sources
 
 - `packages/openapi/src/openapi-module.test.ts`: Integration tests and usage examples.
+- `packages/openapi/src/openapi-module-routes.test.ts`: Default, custom, multi-document, and route-collision examples.
 - `packages/openapi/src/schema-builder.test.ts`: Document builder and schema generation examples.

package/dist/decorators.d.ts

@@ -1,4 +1,4 @@
-import { type Constructor, type MetadataPropertyKey } from '@fluojs/core';
+import type { Constructor, MetadataPropertyKey } from '@fluojs/core';
 import type { OpenApiSchemaObject } from './schema-builder.js';
 /**
  * User-facing operation metadata accepted by `@ApiOperation(...)`.

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

@@ -1,4 +1,4 @@
-import { ensureMetadataSymbol, getStandardMetadataBag } from '@fluojs/core/internal';
+import { ensureRequestPipelineMetadataSymbol, getRequestPipelineMetadataBag } from '@fluojs/core/request-pipeline';
 
 /**
  * User-facing operation metadata accepted by `@ApiOperation(...)`.
@@ -48,9 +48,9 @@ const openApiMethodRequestBodyKey = Symbol.for('fluo.openapi.method-request-body
 const openApiMethodSecurityKey = Symbol.for('fluo.openapi.method-security');
 const openApiMethodSecurityRequirementsKey = Symbol.for('fluo.openapi.method-security-requirements');
 const openApiMethodExcludeEndpointKey = Symbol.for('fluo.openapi.method-exclude-endpoint');
-ensureMetadataSymbol();
+ensureRequestPipelineMetadataSymbol();
 function getMetadataBag(target) {
-  return getStandardMetadataBag(target);
+  return getRequestPipelineMetadataBag(target);
 }
 function cloneUnknown(value) {
   if (value === null || value === undefined) {

package/dist/openapi-module.d.ts

@@ -1,22 +1,30 @@
-import { type HandlerDescriptor, type HandlerSource } from '@fluojs/http';
 import { type AsyncModuleOptions, type Constructor } from '@fluojs/core';
+import { type HandlerDescriptor, type HandlerSource } from '@fluojs/http';
 import { type ModuleType } from '@fluojs/runtime';
 import { type DefaultErrorResponsesPolicy, type OpenApiDocument, type OpenApiSecuritySchemeObject } from './schema-builder.js';
+import { type OpenApiSwaggerUiAssetsOptions } from './swagger-ui.js';
+export type { OpenApiSwaggerUiAssetsOptions } from './swagger-ui.js';
 /**
- * Asset URLs used by the generated Swagger UI HTML page.
+ * Routes owned by one `OpenApiModule` registration.
+ *
+ * @remarks
+ * Paths use the normal `@fluojs/http` route grammar and are normalized before
+ * registration. The defaults remain `/openapi.json` and `/docs`.
  */
-export interface OpenApiSwaggerUiAssetsOptions {
-    cssUrl?: string;
-    jsBundleUrl?: string;
+export interface OpenApiRouteOptions {
+    /** JSON document route. Defaults to `/openapi.json`. */
+    readonly documentPath?: string;
+    /** Swagger UI route. Defaults to `/docs`. */
+    readonly uiPath?: string;
 }
 /**
- * Public options for `OpenApiModule.forRoot(...)` and `OpenApiModule.forRootAsync(...)`.
+ * Public document and route options for `OpenApiModule.forRoot(...)`.
  *
  * @remarks
  * Keep README examples for full controller/module workflows. These options are
  * intended to document the runtime hooks that shape the generated document.
  */
-export interface OpenApiModuleOptions {
+export interface OpenApiModuleOptions extends OpenApiRouteOptions {
     defaultErrorResponsesPolicy?: DefaultErrorResponsesPolicy;
     title: string;
     version: string;
@@ -28,6 +36,14 @@ export interface OpenApiModuleOptions {
     extraModels?: Constructor[];
     documentTransform?: (document: OpenApiDocument) => OpenApiDocument;
 }
+/**
+ * Async OpenAPI registration options with routes fixed before module compilation.
+ *
+ * @remarks
+ * `documentPath` and `uiPath` belong to the outer registration because HTTP
+ * routes are compiled before the injected options factory resolves.
+ */
+export type OpenApiAsyncModuleOptions = AsyncModuleOptions<Omit<OpenApiModuleOptions, keyof OpenApiRouteOptions>> & OpenApiRouteOptions;
 /**
  * Runtime module entrypoint for serving OpenAPI JSON and optional Swagger UI.
  */
@@ -57,7 +73,9 @@ export declare class OpenApiModule {
      * @example
      * ```ts
      * OpenApiModule.forRootAsync({
+     *   documentPath: '/openapi/internal.json',
      *   inject: [ConfigService],
+     *   uiPath: '/docs/internal',
      *   useFactory: (config) => ({
      *     title: config.get('APP_NAME'),
      *     version: config.get('APP_VERSION'),
@@ -65,7 +83,7 @@ export declare class OpenApiModule {
      * });
      * ```
      */
-    static forRootAsync(options: AsyncModuleOptions<OpenApiModuleOptions>): ModuleType;
+    static forRootAsync(options: OpenApiAsyncModuleOptions): ModuleType;
     private static createModule;
 }
 //# sourceMappingURL=openapi-module.d.ts.map

package/dist/openapi-module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"openapi-module.d.ts","sourceRoot":"","sources":["../src/openapi-module.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAEnB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAU,KAAK,kBAAkB,EAAE,KAAK,WAAW,EAA0C,MAAM,cAAc,CAAC;AACzH,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAGhE,OAAO,EAEL,KAAK,2BAA2B,EAChC,KAAK,eAAe,EACpB,KAAK,2BAA2B,EACjC,MAAM,qBAAqB,CAAC;AAQ7B;;GAEG;AACH,MAAM,WAAW,6BAA6B;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC,2BAA2B,CAAC,EAAE,2BAA2B,CAAC;IAC1D,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,CAAC,EAAE,OAAO,CAAC;IACb,WAAW,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC3C,OAAO,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IACnC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,2BAA2B,CAAC,CAAC;IAC9D,eAAe,CAAC,EAAE,6BAA6B,CAAC;IAChD,WAAW,CAAC,EAAE,WAAW,EAAE,CAAC;IAC5B,iBAAiB,CAAC,EAAE,CAAC,QAAQ,EAAE,eAAe,KAAK,eAAe,CAAC;CACpE;AA2GD;;GAEG;AACH,qBAAa,aAAa;IACxB;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,oBAAoB,GAAG,UAAU;IAOzD;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,YAAY,CAAC,OAAO,EAAE,kBAAkB,CAAC,oBAAoB,CAAC,GAAG,UAAU;IAQlF,OAAO,CAAC,MAAM,CAAC,YAAY;CAqE5B"}
+{"version":3,"file":"openapi-module.d.ts","sourceRoot":"","sources":["../src/openapi-module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,kBAAkB,EAAE,KAAK,WAAW,EAAkD,MAAM,cAAc,CAAC;AACzH,OAAO,EAIL,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAGnB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAGhE,OAAO,EAEL,KAAK,2BAA2B,EAChC,KAAK,eAAe,EACpB,KAAK,2BAA2B,EACjC,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAEL,KAAK,6BAA6B,EAEnC,MAAM,iBAAiB,CAAC;AAKzB,YAAY,EAAE,6BAA6B,EAAE,MAAM,iBAAiB,CAAC;AAErE;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,wDAAwD;IACxD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,6CAA6C;IAC7C,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,oBAAqB,SAAQ,mBAAmB;IAC/D,2BAA2B,CAAC,EAAE,2BAA2B,CAAC;IAC1D,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,CAAC,EAAE,OAAO,CAAC;IACb,WAAW,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC3C,OAAO,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IACnC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,2BAA2B,CAAC,CAAC;IAC9D,eAAe,CAAC,EAAE,6BAA6B,CAAC;IAChD,WAAW,CAAC,EAAE,WAAW,EAAE,CAAC;IAC5B,iBAAiB,CAAC,EAAE,CAAC,QAAQ,EAAE,eAAe,KAAK,eAAe,CAAC;CACpE;AAED;;;;;;GAMG;AACH,MAAM,MAAM,yBAAyB,GAAG,kBAAkB,CACxD,IAAI,CAAC,oBAAoB,EAAE,MAAM,mBAAmB,CAAC,CACtD,GAAG,mBAAmB,CAAC;AAgFxB;;GAEG;AACH,qBAAa,aAAa;IACxB;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,oBAAoB,GAAG,UAAU;IASzD;;;;;;;;;;;;;;;;;;OAkBG;IACH,MAAM,CAAC,YAAY,CAAC,OAAO,EAAE,yBAAyB,GAAG,UAAU;IAanE,OAAO,CAAC,MAAM,CAAC,YAAY;CAwE5B"}

package/dist/openapi-module.js

@@ -3,32 +3,40 @@ function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol"
 function _toPrimitive(t, r) { if ("object" != typeof t || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != typeof i) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
 function _setFunctionName(e, t, n) { "symbol" == typeof t && (t = (t = t.description) ? "[" + t + "]" : ""); try { Object.defineProperty(e, "name", { configurable: !0, value: n ? n + " " + t : t }); } catch (e) {} return e; }
 function _checkInRHS(e) { if (Object(e) !== e) throw TypeError("right-hand side of 'in' should be an object, got " + (null !== e ? typeof e : "null")); return e; }
-import { Controller, Get, NotFoundException, createHandlerMapping } from '@fluojs/http';
 import { Inject } from '@fluojs/core';
+import { Controller, createHandlerMapping, Get, NotFoundException } from '@fluojs/http';
 import { defineModule } from '@fluojs/runtime';
 import { OpenApiHandlerRegistry } from './handler-registry.js';
 import { buildOpenApiDocument } from './schema-builder.js';
 import { cloneSnapshotValue, createFrozenSnapshot } from './snapshot.js';
-const SWAGGER_UI_DIST_VERSION = '5.32.2';
-const SWAGGER_UI_DIST_BASE_URL = `https://unpkg.com/swagger-ui-dist@${SWAGGER_UI_DIST_VERSION}`;
-const SWAGGER_UI_CSS_URL = `${SWAGGER_UI_DIST_BASE_URL}/swagger-ui.css`;
-const SWAGGER_UI_BUNDLE_JS_URL = `${SWAGGER_UI_DIST_BASE_URL}/swagger-ui-bundle.js`;
+import { createSwaggerUiHtml, resolveSwaggerUiAssets } from './swagger-ui.js';
+const DEFAULT_DOCUMENT_PATH = '/openapi.json';
+const DEFAULT_UI_PATH = '/docs';
 
 /**
- * Asset URLs used by the generated Swagger UI HTML page.
+ * Routes owned by one `OpenApiModule` registration.
+ *
+ * @remarks
+ * Paths use the normal `@fluojs/http` route grammar and are normalized before
+ * registration. The defaults remain `/openapi.json` and `/docs`.
  */
 
 /**
- * Public options for `OpenApiModule.forRoot(...)` and `OpenApiModule.forRootAsync(...)`.
+ * Public document and route options for `OpenApiModule.forRoot(...)`.
  *
  * @remarks
  * Keep README examples for full controller/module workflows. These options are
  * intended to document the runtime hooks that shape the generated document.
  */
 
-function escapeHtml(value) {
-  return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&#x27;');
-}
+/**
+ * Async OpenAPI registration options with routes fixed before module compilation.
+ *
+ * @remarks
+ * `documentPath` and `uiPath` belong to the outer registration because HTTP
+ * routes are compiled before the injected options factory resolves.
+ */
+
 function cloneRecord(record) {
   if (!record) {
     return undefined;
@@ -43,6 +51,7 @@ function snapshotOpenApiModuleOptions(options) {
   return createFrozenSnapshot({
     defaultErrorResponsesPolicy: options.defaultErrorResponsesPolicy,
     descriptors: options.descriptors ? cloneSnapshotValue(options.descriptors) : undefined,
+    documentPath: options.documentPath,
     documentTransform: options.documentTransform,
     extraModels: options.extraModels ? [...options.extraModels] : undefined,
     securitySchemes: cloneRecord(options.securitySchemes),
@@ -52,38 +61,17 @@ function snapshotOpenApiModuleOptions(options) {
     } : undefined,
     title: options.title,
     ui: options.ui,
+    uiPath: options.uiPath,
     version: options.version
   });
 }
-function resolveSwaggerUiAssets(options) {
+function resolveOpenApiRouteOptions(options) {
+  const normalizePath = path => `/${path.split('/').filter(Boolean).join('/')}`;
   return {
-    cssUrl: options.swaggerUiAssets?.cssUrl ?? SWAGGER_UI_CSS_URL,
-    jsBundleUrl: options.swaggerUiAssets?.jsBundleUrl ?? SWAGGER_UI_BUNDLE_JS_URL
+    documentPath: normalizePath(options.documentPath ?? DEFAULT_DOCUMENT_PATH),
+    uiPath: normalizePath(options.uiPath ?? DEFAULT_UI_PATH)
   };
 }
-function createSwaggerUiHtml(title, assets) {
-  return `<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>${escapeHtml(title)}</title>
-    <link rel="stylesheet" href="${escapeHtml(assets.cssUrl)}" />
-  </head>
-  <body>
-    <div id="swagger-ui"></div>
-    <script src="${escapeHtml(assets.jsBundleUrl)}" crossorigin></script>
-    <script>
-      const specUrl = window.location.pathname.replace(/\/docs\/?$/, '/openapi.json');
-      const swaggerUi = SwaggerUIBundle({
-        url: specUrl,
-        dom_id: '#swagger-ui'
-      });
-      void swaggerUi;
-    </script>
-  </body>
-</html>`;
-}
 function isOpenApiModuleOptions(value) {
   if (typeof value !== 'object' || value === null) {
     return false;
@@ -123,10 +111,11 @@ export class OpenApiModule {
    * ```
    */
   static forRoot(options) {
+    const snapshot = snapshotOpenApiModuleOptions(options);
     return this.createModule({
       scope: 'singleton',
-      useValue: snapshotOpenApiModuleOptions(options)
-    });
+      useValue: snapshot
+    }, resolveOpenApiRouteOptions(snapshot));
   }
 
   /**
@@ -138,7 +127,9 @@ export class OpenApiModule {
    * @example
    * ```ts
    * OpenApiModule.forRootAsync({
+   *   documentPath: '/openapi/internal.json',
    *   inject: [ConfigService],
+   *   uiPath: '/docs/internal',
    *   useFactory: (config) => ({
    *     title: config.get('APP_NAME'),
    *     version: config.get('APP_VERSION'),
@@ -147,13 +138,17 @@ export class OpenApiModule {
    * ```
    */
   static forRootAsync(options) {
+    const routes = resolveOpenApiRouteOptions(options);
     return this.createModule({
       inject: options.inject,
       scope: 'singleton',
-      useFactory: async (...deps) => snapshotOpenApiModuleOptions(await options.useFactory(...deps))
-    });
+      useFactory: async (...deps) => snapshotOpenApiModuleOptions({
+        ...(await options.useFactory(...deps)),
+        ...routes
+      })
+    }, routes);
   }
-  static createModule(optionsProvider) {
+  static createModule(optionsProvider, routes) {
     let _initProto, _initClass;
     const openApiModuleOptionsToken = Symbol('fluo.openapi.module-options');
     const openApiDocumentToken = Symbol('fluo.openapi.document');
@@ -163,7 +158,7 @@ export class OpenApiModule {
         ({
           e: [_initProto],
           c: [_OpenApiController, _initClass]
-        } = _applyDecs(this, [Controller(''), Inject(openApiDocumentToken, openApiModuleOptionsToken)], [[Get('/openapi.json'), 2, "getDocument"], [Get('/docs'), 2, "getSwaggerUi"]]));
+        } = _applyDecs(this, [Controller(''), Inject(openApiDocumentToken, openApiModuleOptionsToken)], [[Get(routes.documentPath), 2, "getDocument"], [Get(routes.uiPath), 2, "getSwaggerUi"]]));
       }
       constructor(document, options) {
         this.document = document;
@@ -178,7 +173,7 @@ export class OpenApiModule {
           throw new NotFoundException('Swagger UI is disabled.');
         }
         context.response.setHeader('content-type', 'text/html; charset=utf-8');
-        return createSwaggerUiHtml(this.options.title, resolveSwaggerUiAssets(this.options));
+        return createSwaggerUiHtml(this.options.title, resolveSwaggerUiAssets(this.options.swaggerUiAssets), routes);
       }
       static {
         _initClass();

package/dist/schema-builder.js

@@ -1,4 +1,4 @@
-import { getDtoBindingSchema, getDtoValidationSchema } from '@fluojs/core/internal';
+import { getDtoBindingSchema, getDtoValidationSchema } from '@fluojs/core/request-pipeline';
 import { getControllerTags, getMethodApiMetadata } from './decorators.js';
 import { cloneSnapshotValue } from './snapshot.js';
 

package/dist/swagger-ui.d.ts

@@ -0,0 +1,29 @@
+type SwaggerUiRoutes = {
+    readonly documentPath: string;
+    readonly uiPath: string;
+};
+/**
+ * Asset URLs used by the generated Swagger UI HTML page.
+ */
+export interface OpenApiSwaggerUiAssetsOptions {
+    cssUrl?: string;
+    jsBundleUrl?: string;
+}
+/**
+ * Resolve pinned or caller-provided Swagger UI asset URLs.
+ *
+ * @param assets Optional caller-provided asset URLs.
+ * @returns Complete asset URLs for generated Swagger UI HTML.
+ */
+export declare function resolveSwaggerUiAssets(assets: OpenApiSwaggerUiAssetsOptions | undefined): Required<OpenApiSwaggerUiAssetsOptions>;
+/**
+ * Render Swagger UI HTML for one configured OpenAPI document route.
+ *
+ * @param title Document title rendered into the page.
+ * @param assets Complete Swagger UI asset URLs.
+ * @param routes Normalized JSON document and UI routes.
+ * @returns A standalone Swagger UI HTML document.
+ */
+export declare function createSwaggerUiHtml(title: string, assets: Required<OpenApiSwaggerUiAssetsOptions>, routes: SwaggerUiRoutes): string;
+export {};
+//# sourceMappingURL=swagger-ui.d.ts.map

package/dist/swagger-ui.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"swagger-ui.d.ts","sourceRoot":"","sources":["../src/swagger-ui.ts"],"names":[],"mappings":"AAKA,KAAK,eAAe,GAAG;IACrB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,6BAA6B;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAsBD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,6BAA6B,GAAG,SAAS,GAChD,QAAQ,CAAC,6BAA6B,CAAC,CAKzC;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,QAAQ,CAAC,6BAA6B,CAAC,EAC/C,MAAM,EAAE,eAAe,GACtB,MAAM,CA6BR"}

package/dist/swagger-ui.js

@@ -0,0 +1,67 @@
+const SWAGGER_UI_DIST_VERSION = '5.32.2';
+const SWAGGER_UI_DIST_BASE_URL = `https://unpkg.com/swagger-ui-dist@${SWAGGER_UI_DIST_VERSION}`;
+const SWAGGER_UI_CSS_URL = `${SWAGGER_UI_DIST_BASE_URL}/swagger-ui.css`;
+const SWAGGER_UI_BUNDLE_JS_URL = `${SWAGGER_UI_DIST_BASE_URL}/swagger-ui-bundle.js`;
+
+/**
+ * Asset URLs used by the generated Swagger UI HTML page.
+ */
+
+function escapeHtml(value) {
+  return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&#x27;');
+}
+function escapeRegularExpression(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function serializeInlineScriptString(value) {
+  return JSON.stringify(value).replace(/</g, '\\u003c').replace(/>/g, '\\u003e').replace(/&/g, '\\u0026');
+}
+
+/**
+ * Resolve pinned or caller-provided Swagger UI asset URLs.
+ *
+ * @param assets Optional caller-provided asset URLs.
+ * @returns Complete asset URLs for generated Swagger UI HTML.
+ */
+export function resolveSwaggerUiAssets(assets) {
+  return {
+    cssUrl: assets?.cssUrl ?? SWAGGER_UI_CSS_URL,
+    jsBundleUrl: assets?.jsBundleUrl ?? SWAGGER_UI_BUNDLE_JS_URL
+  };
+}
+
+/**
+ * Render Swagger UI HTML for one configured OpenAPI document route.
+ *
+ * @param title Document title rendered into the page.
+ * @param assets Complete Swagger UI asset URLs.
+ * @param routes Normalized JSON document and UI routes.
+ * @returns A standalone Swagger UI HTML document.
+ */
+export function createSwaggerUiHtml(title, assets, routes) {
+  const uiPathPattern = routes.uiPath === '/' ? '/?$' : `${escapeRegularExpression(routes.uiPath)}/?$`;
+  return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>${escapeHtml(title)}</title>
+    <link rel="stylesheet" href="${escapeHtml(assets.cssUrl)}" />
+  </head>
+  <body>
+    <div id="swagger-ui"></div>
+    <script src="${escapeHtml(assets.jsBundleUrl)}" crossorigin></script>
+    <script>
+      const specUrl = window.location.pathname.replace(
+        new RegExp(${serializeInlineScriptString(uiPathPattern)}),
+        () => ${serializeInlineScriptString(routes.documentPath)}
+      );
+      const swaggerUi = SwaggerUIBundle({
+        url: specUrl,
+        dom_id: '#swagger-ui'
+      });
+      void swaggerUi;
+    </script>
+  </body>
+</html>`;
+}

package/package.json

@@ -9,7 +9,7 @@
     "documentation",
     "rest"
   ],
-  "version": "1.0.3",
+  "version": "1.1.0",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -36,10 +36,10 @@
     "dist"
   ],
   "dependencies": {
-    "@fluojs/http": "^1.1.0",
-    "@fluojs/validation": "^1.0.4",
-    "@fluojs/core": "^1.0.3",
-    "@fluojs/runtime": "^1.1.1"
+    "@fluojs/core": "^1.1.0",
+    "@fluojs/http": "^2.0.1",
+    "@fluojs/runtime": "^2.0.1",
+    "@fluojs/validation": "^1.0.6"
   },
   "devDependencies": {
     "vitest": "^3.2.4"