@fluojs/openapi 1.0.0-beta.4 → 1.0.0-beta.5

package/README.ko.md

@@ -89,7 +89,10 @@ HTTP 핸들러가 `@fluojs/http`의 `@Produces(...)`를 선언하면, 생성된
 같은 scheme에 대해 여러 `@ApiSecurity()` 데코레이터를 쌓으면, 해당 scheme의 scope가 하나의 누적 OpenAPI security requirement로 병합됩니다. 따라서 라우트가 `['reports:read']`와 `['reports:write', 'reports:read']`처럼 겹치는 scope를 선언해도 OAuth 스타일 요구사항은 결정적으로 유지되며, 서로 다른 scheme은 별도 requirement로 남습니다.
 
 ### 결정적인 Swagger UI 자산
-`ui: true`를 활성화하면 생성되는 `/docs` 페이지는 정확한 `swagger-ui-dist` 버전의 자산을 참조하여 패키지 릴리스마다 동일한 동작을 유지합니다.
+`ui: true`를 활성화하면 생성되는 `/docs` 페이지는 정확한 `swagger-ui-dist` 버전의 자산을 참조하여 패키지 릴리스마다 동일한 동작을 유지합니다. 오프라인 또는 CSP 제어 환경에서 자체 호스팅 자산이 필요하면 `swaggerUiAssets.cssUrl`과 `swaggerUiAssets.jsBundleUrl`을 설정하세요. 생성된 HTML은 해당 URL을 이스케이프하며 Swagger UI 인스턴스를 `window.ui`에 노출하지 않습니다.
+
+### 모듈 옵션 결정성
+`OpenApiModule.forRoot(...)`는 등록 시점에 옵션을 스냅샷하고 freeze합니다. 등록 후 원본 options 객체, `sources`, `descriptors`, `securitySchemes`, `extraModels`, `swaggerUiAssets`를 변경해도 제공되는 OpenAPI 문서나 `/docs` HTML은 바뀌지 않습니다. `OpenApiModule.forRootAsync(...)`도 async factory가 resolve된 뒤 같은 스냅샷을 적용하며, factory 실패는 bootstrap 중 전파됩니다.
 
 ## 공개 API
 
@@ -99,6 +102,8 @@ HTTP 핸들러가 `@fluojs/http`의 `@Produces(...)`를 선언하면, 생성된
 - `ApiBearerAuth`, `ApiSecurity`: 보안 요구사항 데코레이터.
 - `ApiExcludeEndpoint`: 특정 핸들러를 문서화에서 제외.
 - `buildOpenApiDocument`: 프로그래밍 방식의 문서 빌더 (저수준).
+- `OpenApiHandlerRegistry`: 고급 통합에서 문서 생성 전에 handler descriptor를 스냅샷하는 mutable descriptor registry.
+- `getControllerTags`, `getMethodApiMetadata`: 고급 테스트와 통합 tooling을 위한 metadata reader.
 - `OpenApiSchemaObject`: 명시적 `@ApiBody(...)` 및 `@ApiResponse(...)` 스키마를 위한 타입화된 스키마 표면입니다. OpenAPI 3.1 조합(`allOf`, `oneOf`, `anyOf`), 객체/배열 제약, examples/defaults, 읽기/쓰기/Deprecated 주석을 포함합니다.
 
 ## 관련 패키지

package/README.md

@@ -89,7 +89,10 @@ Easily document authentication requirements like Bearer tokens or API keys using
 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.
 
 ### 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.
+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`.
+
+### 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. `OpenApiModule.forRootAsync(...)` applies the same snapshot once the async factory resolves, and factory failures propagate during bootstrap.
 
 ## Public API
 
@@ -99,6 +102,8 @@ When `ui: true` is enabled, the generated `/docs` page references an exact `swag
 - `ApiBearerAuth`, `ApiSecurity`: Security requirement decorators.
 - `ApiExcludeEndpoint`: Omit specific handlers from documentation.
 - `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.
 - `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.
 
 ## Related Packages

package/dist/openapi-module.d.ts

@@ -2,6 +2,13 @@ import { type HandlerDescriptor, type HandlerSource } from '@fluojs/http';
 import { type AsyncModuleOptions, type Constructor } from '@fluojs/core';
 import { type ModuleType } from '@fluojs/runtime';
 import { type DefaultErrorResponsesPolicy, type OpenApiDocument, type OpenApiSecuritySchemeObject } from './schema-builder.js';
+/**
+ * Asset URLs used by the generated Swagger UI HTML page.
+ */
+export interface OpenApiSwaggerUiAssetsOptions {
+    cssUrl?: string;
+    jsBundleUrl?: string;
+}
 /**
  * Public options for `OpenApiModule.forRoot(...)` and `OpenApiModule.forRootAsync(...)`.
  *
@@ -17,6 +24,7 @@ export interface OpenApiModuleOptions {
     descriptors?: readonly HandlerDescriptor[];
     sources?: readonly HandlerSource[];
     securitySchemes?: Record<string, OpenApiSecuritySchemeObject>;
+    swaggerUiAssets?: OpenApiSwaggerUiAssetsOptions;
     extraModels?: Constructor[];
     documentTransform?: (document: OpenApiDocument) => OpenApiDocument;
 }

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,EAAiC,MAAM,cAAc,CAAC;AAChH,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAGhE,OAAO,EAEL,KAAK,2BAA2B,EAChC,KAAK,eAAe,EACpB,KAAK,2BAA2B,EACjC,MAAM,qBAAqB,CAAC;AAO7B;;;;;;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,WAAW,CAAC,EAAE,WAAW,EAAE,CAAC;IAC5B,iBAAiB,CAAC,EAAE,CAAC,QAAQ,EAAE,eAAe,KAAK,eAAe,CAAC;CACpE;AAsED;;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,EAKL,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAEnB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAU,KAAK,kBAAkB,EAAE,KAAK,WAAW,EAAiC,MAAM,cAAc,CAAC;AAChH,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAGhE,OAAO,EAEL,KAAK,2BAA2B,EAChC,KAAK,eAAe,EACpB,KAAK,2BAA2B,EACjC,MAAM,qBAAqB,CAAC;AAO7B;;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;AA6ID;;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"}

package/dist/openapi-module.js

@@ -13,6 +13,10 @@ const SWAGGER_UI_DIST_BASE_URL = `https://unpkg.com/swagger-ui-dist@${SWAGGER_UI
 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.
+ */
+
 /**
  * Public options for `OpenApiModule.forRoot(...)` and `OpenApiModule.forRootAsync(...)`.
  *
@@ -24,24 +28,82 @@ const SWAGGER_UI_BUNDLE_JS_URL = `${SWAGGER_UI_DIST_BASE_URL}/swagger-ui-bundle.
 function escapeHtml(value) {
   return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&#x27;');
 }
-function createSwaggerUiHtml(title) {
+function cloneRecord(record) {
+  if (!record) {
+    return undefined;
+  }
+  const clone = {};
+  for (const [key, value] of Object.entries(record)) {
+    clone[key] = cloneSnapshotValue(value);
+  }
+  return clone;
+}
+function cloneSnapshotValue(value) {
+  if (value === null || value === undefined) {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map(entry => cloneSnapshotValue(entry));
+  }
+  if (typeof value !== 'object') {
+    return value;
+  }
+  const clone = {};
+  for (const key of Reflect.ownKeys(value)) {
+    clone[key] = cloneSnapshotValue(value[key]);
+  }
+  return clone;
+}
+function deepFreeze(value) {
+  if (value === null || typeof value !== 'object') {
+    return value;
+  }
+  for (const key of Reflect.ownKeys(value)) {
+    deepFreeze(value[key]);
+  }
+  return Object.freeze(value);
+}
+function snapshotOpenApiModuleOptions(options) {
+  return deepFreeze({
+    defaultErrorResponsesPolicy: options.defaultErrorResponsesPolicy,
+    descriptors: options.descriptors ? cloneSnapshotValue(options.descriptors) : undefined,
+    documentTransform: options.documentTransform,
+    extraModels: options.extraModels ? [...options.extraModels] : undefined,
+    securitySchemes: cloneRecord(options.securitySchemes),
+    sources: options.sources ? cloneSnapshotValue(options.sources) : undefined,
+    swaggerUiAssets: options.swaggerUiAssets ? {
+      ...options.swaggerUiAssets
+    } : undefined,
+    title: options.title,
+    ui: options.ui,
+    version: options.version
+  });
+}
+function resolveSwaggerUiAssets(options) {
+  return {
+    cssUrl: options.swaggerUiAssets?.cssUrl ?? SWAGGER_UI_CSS_URL,
+    jsBundleUrl: options.swaggerUiAssets?.jsBundleUrl ?? SWAGGER_UI_BUNDLE_JS_URL
+  };
+}
+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="${SWAGGER_UI_CSS_URL}" />
+    <link rel="stylesheet" href="${escapeHtml(assets.cssUrl)}" />
   </head>
   <body>
     <div id="swagger-ui"></div>
-    <script src="${SWAGGER_UI_BUNDLE_JS_URL}" crossorigin></script>
+    <script src="${escapeHtml(assets.jsBundleUrl)}" crossorigin></script>
     <script>
       const specUrl = window.location.pathname.replace(/\/docs\/?$/, '/openapi.json');
-      window.ui = SwaggerUIBundle({
+      const swaggerUi = SwaggerUIBundle({
         url: specUrl,
         dom_id: '#swagger-ui'
       });
+      void swaggerUi;
     </script>
   </body>
 </html>`;
@@ -87,7 +149,7 @@ export class OpenApiModule {
   static forRoot(options) {
     return this.createModule({
       scope: 'singleton',
-      useValue: options
+      useValue: snapshotOpenApiModuleOptions(options)
     });
   }
 
@@ -112,7 +174,7 @@ export class OpenApiModule {
     return this.createModule({
       inject: options.inject,
       scope: 'singleton',
-      useFactory: options.useFactory
+      useFactory: async (...deps) => snapshotOpenApiModuleOptions(await options.useFactory(...deps))
     });
   }
   static createModule(optionsProvider) {
@@ -140,7 +202,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);
+        return createSwaggerUiHtml(this.options.title, resolveSwaggerUiAssets(this.options));
       }
       static {
         _initClass();

package/package.json

@@ -9,7 +9,7 @@
     "documentation",
     "rest"
   ],
-  "version": "1.0.0-beta.4",
+  "version": "1.0.0-beta.5",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -36,10 +36,10 @@
     "dist"
   ],
   "dependencies": {
-    "@fluojs/core": "^1.0.0-beta.2",
-    "@fluojs/validation": "^1.0.0-beta.1",
-    "@fluojs/http": "^1.0.0-beta.4",
-    "@fluojs/runtime": "^1.0.0-beta.5"
+    "@fluojs/core": "^1.0.0-beta.3",
+    "@fluojs/validation": "^1.0.0-beta.2",
+    "@fluojs/http": "^1.0.0-beta.9",
+    "@fluojs/runtime": "^1.0.0-beta.9"
   },
   "devDependencies": {
     "vitest": "^3.2.4"