@rsdk/cli.cmd.autodoc 6.0.0-next.1 → 6.0.0-next.11

package/src/generators/openapi-json/config.schema.spec.ts

@@ -0,0 +1,265 @@
+import { TypeBoxValidator } from '@rsdk/common';
+import { parse } from 'yaml';
+
+import { OpenApiConfigSchema } from './config.schema';
+
+describe('OpenAPI Config Schema', () => {
+  const validator = new TypeBoxValidator(OpenApiConfigSchema);
+
+  it('should validate minimal config', () => {
+    const config = parse(`
+      out: openapi.json
+      title: Test API
+      version: 1.0.0
+      description: Test API Description
+    `);
+
+    const { isValid, errors } = validator.check(config);
+
+    expect(isValid).toBe(true);
+    expect(errors).toHaveLength(0);
+  });
+
+  it('should validate minimal config', () => {
+    const config = parse(`
+      out: openapi.json
+      title: Test API
+      version: '1.0.0'
+      description: Test API Description
+    `);
+
+    const { isValid, errors } = validator.check(config);
+
+    expect(isValid).toBe(true);
+    expect(errors).toHaveLength(0);
+  });
+
+  it('should validate config with zones', () => {
+    const config = parse(`
+      out: openapi.json
+      title: Test API
+      version: '1.0.0'
+      description: Test API Description
+      includeZones:
+        - public
+        - api:web
+      excludeZones:
+        - __internal
+    `);
+
+    const { isValid, errors } = validator.check(config);
+
+    expect(isValid).toBe(true);
+    expect(errors).toHaveLength(0);
+  });
+
+  it('should validate config without optional fields', () => {
+    const config = parse(`
+      out: openapi.json
+      version: '1.0.0'
+    `);
+
+    const { isValid, errors } = validator.check(config);
+
+    expect(isValid).toBe(true);
+    expect(errors).toHaveLength(0);
+  });
+
+  describe('Security Schemes', () => {
+    it('should validate API Key auth', () => {
+      const config = parse(`
+        out: openapi.json
+        title: Test API
+        version: '1.0.0'
+        description: Test API Description
+        security:
+          ApiKeyAuth:
+            type: apiKey
+            in: header
+            name: x-api-key
+            description: API Key Authentication
+      `);
+
+      const { isValid, errors } = validator.check(config);
+
+      expect(isValid).toBe(true);
+      expect(errors).toHaveLength(0);
+    });
+
+    it('should validate Bearer auth', () => {
+      const config = parse(`
+        out: openapi.json
+        title: Test API
+        version: '1.0.0'
+        description: Test API Description
+        security:
+          BearerAuth:
+            type: http
+            scheme: bearer
+            bearerFormat: JWT
+            description: JWT Bearer Authentication
+      `);
+
+      const { isValid, errors } = validator.check(config);
+
+      expect(isValid).toBe(true);
+      expect(errors).toHaveLength(0);
+    });
+
+    it('should validate Basic auth', () => {
+      const config = parse(`
+        out: openapi.json
+        title: Test API
+        version: '1.0.0'
+        description: Test API Description
+        security:
+          BasicAuth:
+            type: http
+            scheme: basic
+            description: Basic Authentication
+      `);
+
+      const { isValid, errors } = validator.check(config);
+
+      expect(isValid).toBe(true);
+      expect(errors).toHaveLength(0);
+    });
+
+    it('should validate OAuth2 auth', () => {
+      const config = parse(`
+        out: openapi.json
+        title: Test API
+        version: '1.0.0'
+        description: Test API Description
+        security:
+          OAuth2Auth:
+            type: oauth2
+            flows:
+              implicit:
+                authorizationUrl: https://auth.example.com/oauth/authorize
+                scopes:
+                  read: Read access
+                  write: Write access
+      `);
+
+      const { isValid, errors } = validator.check(config);
+
+      for (const error of errors) {
+        console.log(error);
+      }
+
+      expect(isValid).toBe(true);
+      expect(errors).toHaveLength(0);
+    });
+
+    it('should validate multiple security schemes', () => {
+      const config = parse(`
+        out: openapi.json
+        title: Test API
+        version: '1.0.0'
+        description: Test API Description
+        security:
+          BearerAuth:
+            type: http
+            scheme: bearer
+            bearerFormat: JWT
+            description: JWT Bearer Authentication
+          
+          ApiKeyAuth:
+            type: apiKey
+            in: header
+            name: x-api-key
+            description: API Key Authentication
+          
+          OAuth2Auth:
+            type: oauth2
+            description: OAuth2 Authentication
+            flows:
+              implicit:
+                authorizationUrl: https://auth.example.com/oauth/authorize
+                scopes:
+                  read: Read access
+                  write: Write access
+      `);
+
+      const { isValid, errors } = validator.check(config);
+
+      expect(isValid).toBe(true);
+      expect(errors).toHaveLength(0);
+    });
+
+    it('should validate cookie-based auth', () => {
+      const config = parse(`
+        out: openapi/openapi.web.json
+        includeZones:
+          - api:web
+        title: Web API
+        version: '1.3'
+        description: Web API methods
+        security:
+          SessionCookie:
+            type: apiKey
+            in: cookie
+            name: sessionId
+            description: Cookie-based authentication
+      `);
+
+      const { isValid, errors } = validator.check(config);
+
+      expect(isValid).toBe(true);
+      expect(errors).toHaveLength(0);
+    });
+  });
+
+  describe('Validation Errors', () => {
+    it('should fail on invalid security type', () => {
+      const config = parse(`
+        out: openapi.json
+        title: Test API
+        version: 1.0.0
+        description: Test API Description
+        security:
+          InvalidAuth:
+            type: invalid
+      `);
+
+      const { isValid, errors } = validator.check(config);
+
+      expect(isValid).toBe(false);
+      expect(errors).toHaveLength(2);
+    });
+
+    it('should fail on missing required fields', () => {
+      const config = parse(`
+        out: openapi.json
+        title: Test API
+        description: Test API Description
+      `);
+
+      const { isValid, errors } = validator.check(config);
+
+      expect(isValid).toBe(true);
+      expect(errors).toHaveLength(0);
+    });
+
+    it('should fail on invalid OAuth2 flow configuration', () => {
+      const config = parse(`
+        out: openapi.json
+        title: Test API
+        version: 1.0.0
+        description: Test API Description
+        security:
+          - type: oauth2
+            schemaName: OAuth2Auth
+            flows:
+              implicit:
+                scopes: invalid
+      `);
+
+      const { isValid, errors } = validator.check(config);
+
+      expect(isValid).toBe(false);
+      expect(errors.length).toBeGreaterThan(0);
+    });
+  });
+});

package/src/generators/openapi-json/config.schema.ts

@@ -0,0 +1,37 @@
+import { OpenApiOptions } from '@rsdk/http.openapi';
+import type { Static } from '@sinclair/typebox';
+import { Type } from '@sinclair/typebox';
+
+/**
+ * Configuration schema for OpenAPI document generation.
+ * @example
+ * {
+ *   "out": "openapi.json",
+ *   "app": "./dist/app.js",
+ *   "title": "My API",
+ *   "version": "1.0.0",
+ *   "description": "API Description",
+ *   "includeZones": ["public"],
+ *   "excludeZones": ["internal"],
+ *   "security": {
+ *     "jwt": {
+ *       "type": "http",
+ *       "scheme": "bearer",
+ *       "bearerFormat": "JWT",
+ *       "name": "JWT Auth"
+ *     }
+ *   }
+ * }
+ */
+export const OpenApiConfigSchema = Type.Intersect([
+  Type.Partial(OpenApiOptions),
+  Type.Object({
+    /** Output file path for the generated OpenAPI document */
+    out: Type.Optional(Type.String()),
+
+    /** Path to the application file (usually `dist/app.js`) */
+    app: Type.Optional(Type.String()),
+  }),
+]);
+
+export type OpenApiConfigSchema = Static<typeof OpenApiConfigSchema>;

package/src/generators/openapi-json/index.ts

@@ -0,0 +1,2 @@
+export * from './openapi-json.generator';
+export * from './config.schema';

package/src/generators/openapi-json/openapi-json.generator.ts

@@ -0,0 +1,53 @@
+import type { PlatformApp, PlatformContext } from '@rsdk/core';
+import { OpenApiGenerator } from '@rsdk/http.openapi';
+import { LoggerFactory } from '@rsdk/logging';
+
+import { FileGenerator } from '../file-generator.interface';
+
+import type { OpenApiConfigSchema } from './config.schema';
+
+/**
+ * Here we don't need `out` and `app`,
+ * but `title`, `version` and `description` are required.
+ */
+export type OpenApiGeneratorOptions = Omit<OpenApiConfigSchema, 'out' | 'app'> &
+  Required<Pick<OpenApiConfigSchema, 'title' | 'version' | 'description'>>;
+
+export class OpenApiFileGenerator extends FileGenerator {
+  private readonly context: PlatformContext;
+  private readonly options: Partial<OpenApiGeneratorOptions>;
+
+  constructor(
+    app: PlatformApp,
+    options: Partial<OpenApiGeneratorOptions> = {},
+  ) {
+    super(LoggerFactory.create(OpenApiFileGenerator));
+    this.context = app.context;
+    this.options = options;
+  }
+
+  protected async getContent(): Promise<string> {
+    this.logger.info('Generate openapi starting');
+
+    const options = await this.resolveOptions(this.context, this.options);
+    const generator = new OpenApiGenerator(this.context, options);
+    const document = await generator.generate();
+
+    this.logger.info('Generate openapi finished');
+    return JSON.stringify(document, null, 2);
+  }
+
+  private async resolveOptions(
+    context: PlatformContext,
+    passed: Partial<OpenApiGeneratorOptions>,
+  ): Promise<OpenApiGeneratorOptions> {
+    const appMetadata = await context.getMetadata();
+    const defaults: OpenApiGeneratorOptions = {
+      title: appMetadata.name,
+      version: appMetadata.version,
+      description: appMetadata.description,
+    };
+
+    return { ...defaults, ...passed };
+  }
+}

package/src/generators/openapi-json/schemas/config.schema.spec.ts

@@ -0,0 +1,265 @@
+import { TypeBoxValidator } from '@rsdk/common';
+import { parse } from 'yaml';
+
+import { OpenApiConfigSchema } from './config.schema';
+
+describe('OpenAPI Config Schema', () => {
+  const validator = new TypeBoxValidator(OpenApiConfigSchema);
+
+  it('should validate minimal config', () => {
+    const config = parse(`
+      out: openapi.json
+      title: Test API
+      version: 1.0.0
+      description: Test API Description
+    `);
+
+    const { isValid, errors } = validator.check(config);
+
+    expect(isValid).toBe(true);
+    expect(errors).toHaveLength(0);
+  });
+
+  it('should validate minimal config', () => {
+    const config = parse(`
+      out: openapi.json
+      title: Test API
+      version: '1.0.0'
+      description: Test API Description
+    `);
+
+    const { isValid, errors } = validator.check(config);
+
+    expect(isValid).toBe(true);
+    expect(errors).toHaveLength(0);
+  });
+
+  it('should validate config with zones', () => {
+    const config = parse(`
+      out: openapi.json
+      title: Test API
+      version: '1.0.0'
+      description: Test API Description
+      includeZones:
+        - public
+        - api:web
+      excludeZones:
+        - __internal
+    `);
+
+    const { isValid, errors } = validator.check(config);
+
+    expect(isValid).toBe(true);
+    expect(errors).toHaveLength(0);
+  });
+
+  it('should validate config without optional fields', () => {
+    const config = parse(`
+      out: openapi.json
+      version: '1.0.0'
+    `);
+
+    const { isValid, errors } = validator.check(config);
+
+    expect(isValid).toBe(true);
+    expect(errors).toHaveLength(0);
+  });
+
+  describe('Security Schemes', () => {
+    it('should validate API Key auth', () => {
+      const config = parse(`
+        out: openapi.json
+        title: Test API
+        version: '1.0.0'
+        description: Test API Description
+        security:
+          ApiKeyAuth:
+            type: apiKey
+            in: header
+            name: x-api-key
+            description: API Key Authentication
+      `);
+
+      const { isValid, errors } = validator.check(config);
+
+      expect(isValid).toBe(true);
+      expect(errors).toHaveLength(0);
+    });
+
+    it('should validate Bearer auth', () => {
+      const config = parse(`
+        out: openapi.json
+        title: Test API
+        version: '1.0.0'
+        description: Test API Description
+        security:
+          BearerAuth:
+            type: http
+            scheme: bearer
+            bearerFormat: JWT
+            description: JWT Bearer Authentication
+      `);
+
+      const { isValid, errors } = validator.check(config);
+
+      expect(isValid).toBe(true);
+      expect(errors).toHaveLength(0);
+    });
+
+    it('should validate Basic auth', () => {
+      const config = parse(`
+        out: openapi.json
+        title: Test API
+        version: '1.0.0'
+        description: Test API Description
+        security:
+          BasicAuth:
+            type: http
+            scheme: basic
+            description: Basic Authentication
+      `);
+
+      const { isValid, errors } = validator.check(config);
+
+      expect(isValid).toBe(true);
+      expect(errors).toHaveLength(0);
+    });
+
+    it('should validate OAuth2 auth', () => {
+      const config = parse(`
+        out: openapi.json
+        title: Test API
+        version: '1.0.0'
+        description: Test API Description
+        security:
+          OAuth2Auth:
+            type: oauth2
+            flows:
+              implicit:
+                authorizationUrl: https://auth.example.com/oauth/authorize
+                scopes:
+                  read: Read access
+                  write: Write access
+      `);
+
+      const { isValid, errors } = validator.check(config);
+
+      for (const error of errors) {
+        console.log(error);
+      }
+
+      expect(isValid).toBe(true);
+      expect(errors).toHaveLength(0);
+    });
+
+    it('should validate multiple security schemes', () => {
+      const config = parse(`
+        out: openapi.json
+        title: Test API
+        version: '1.0.0'
+        description: Test API Description
+        security:
+          BearerAuth:
+            type: http
+            scheme: bearer
+            bearerFormat: JWT
+            description: JWT Bearer Authentication
+          
+          ApiKeyAuth:
+            type: apiKey
+            in: header
+            name: x-api-key
+            description: API Key Authentication
+          
+          OAuth2Auth:
+            type: oauth2
+            description: OAuth2 Authentication
+            flows:
+              implicit:
+                authorizationUrl: https://auth.example.com/oauth/authorize
+                scopes:
+                  read: Read access
+                  write: Write access
+      `);
+
+      const { isValid, errors } = validator.check(config);
+
+      expect(isValid).toBe(true);
+      expect(errors).toHaveLength(0);
+    });
+
+    it('should validate cookie-based auth', () => {
+      const config = parse(`
+        out: openapi/openapi.web.json
+        includeZones:
+          - api:web
+        title: Web API
+        version: '1.3'
+        description: Web API methods
+        security:
+          SessionCookie:
+            type: apiKey
+            in: cookie
+            name: sessionId
+            description: Cookie-based authentication
+      `);
+
+      const { isValid, errors } = validator.check(config);
+
+      expect(isValid).toBe(true);
+      expect(errors).toHaveLength(0);
+    });
+  });
+
+  describe('Validation Errors', () => {
+    it('should fail on invalid security type', () => {
+      const config = parse(`
+        out: openapi.json
+        title: Test API
+        version: 1.0.0
+        description: Test API Description
+        security:
+          InvalidAuth:
+            type: invalid
+      `);
+
+      const { isValid, errors } = validator.check(config);
+
+      expect(isValid).toBe(false);
+      expect(errors).toHaveLength(2);
+    });
+
+    it('should fail on missing required fields', () => {
+      const config = parse(`
+        out: openapi.json
+        title: Test API
+        description: Test API Description
+      `);
+
+      const { isValid, errors } = validator.check(config);
+
+      expect(isValid).toBe(true);
+      expect(errors).toHaveLength(0);
+    });
+
+    it('should fail on invalid OAuth2 flow configuration', () => {
+      const config = parse(`
+        out: openapi.json
+        title: Test API
+        version: 1.0.0
+        description: Test API Description
+        security:
+          - type: oauth2
+            schemaName: OAuth2Auth
+            flows:
+              implicit:
+                scopes: invalid
+      `);
+
+      const { isValid, errors } = validator.check(config);
+
+      expect(isValid).toBe(false);
+      expect(errors.length).toBeGreaterThan(0);
+    });
+  });
+});

package/src/generators/openapi-json/schemas/config.schema.ts

@@ -0,0 +1,37 @@
+import { OpenApiOptions } from '@rsdk/http.openapi';
+import type { Static } from '@sinclair/typebox';
+import { Type } from '@sinclair/typebox';
+
+/**
+ * Configuration schema for OpenAPI document generation.
+ * @example
+ * {
+ *   "out": "openapi.json",
+ *   "app": "./dist/app.js",
+ *   "title": "My API",
+ *   "version": "1.0.0",
+ *   "description": "API Description",
+ *   "includeZones": ["public"],
+ *   "excludeZones": ["internal"],
+ *   "security": {
+ *     "jwt": {
+ *       "type": "http",
+ *       "scheme": "bearer",
+ *       "bearerFormat": "JWT",
+ *       "name": "JWT Auth"
+ *     }
+ *   }
+ * }
+ */
+export const OpenApiConfigSchema = Type.Intersect([
+  Type.Partial(OpenApiOptions),
+  Type.Object({
+    /** Output file path for the generated OpenAPI document */
+    out: Type.Optional(Type.String()),
+
+    /** Path to the application file (usually `dist/app.js`) */
+    app: Type.Optional(Type.String()),
+  }),
+]);
+
+export type OpenApiConfigSchema = Static<typeof OpenApiConfigSchema>;

package/src/generators/openapi-json/schemas/index.ts

@@ -0,0 +1 @@
+export * from './config.schema';

package/src/generators/rsdk-json/index.ts

@@ -0,0 +1 @@
+export * from './rsdk-json.generator';

package/src/generators/rsdk-json/rsdk-json.generator.ts

@@ -0,0 +1,24 @@
+import type { PlatformApp } from '@rsdk/core';
+import { LoggerFactory } from '@rsdk/logging';
+import type { Resource } from '@rsdk/metadata';
+
+import { FileGenerator } from '../file-generator.interface';
+
+export class RsdkFileGenerator extends FileGenerator {
+  constructor(private readonly app: PlatformApp) {
+    super(LoggerFactory.create(RsdkFileGenerator));
+  }
+
+  protected async getContent(): Promise<string> {
+    const rsdkMetadata = await this.getAllResources();
+    const metadata = await this.app.getMetadata();
+
+    return JSON.stringify({ metadata, rsdkMetadata }, null, 2);
+  }
+
+  private async getAllResources(): Promise<Resource<unknown>[]> {
+    const provider = await this.app.context.getRsdkMetadataProvider();
+
+    return provider.get();
+  }
+}

package/src/index.ts

@@ -0,0 +1 @@
+export { AutodocCommand as default } from './commands/autodoc.cmd';

package/tsconfig.build.json

@@ -0,0 +1,12 @@
+{
+  "extends": "./tsconfig.json",
+  "exclude": [
+    "node_modules",
+    "dist",
+    "test",
+    "**/*.spec.ts",
+    "**/*.test.ts",
+    "**/*.test.e2e.ts",
+    "**/*.test.manual-e2e.ts",
+  ]
+}