@travetto/openapi 3.0.2 → 3.1.0-rc.0

package/README.md

@@ -1,6 +1,7 @@
 <!-- This file was generated by @travetto/doc and should not be modified directly -->
-<!-- Please modify https://github.com/travetto/travetto/tree/main/module/openapi/DOC.ts and execute "npx trv doc" to rebuild -->
+<!-- Please modify https://github.com/travetto/travetto/tree/main/module/openapi/DOC.tsx and execute "npx trv doc" to rebuild -->
 # OpenAPI Specification
+
 ## OpenAPI integration support for the Travetto framework
 
 **Install: @travetto/openapi**
@@ -12,7 +13,7 @@ npm install @travetto/openapi
 yarn add @travetto/openapi
 ```
 
-In the [RESTful API](https://github.com/travetto/travetto/tree/main/module/rest#readme "Declarative api for RESTful APIs with support for the dependency injection module.") module, the controllers and endpoints can be described via decorators, comments, or typings. This only provides the general metadata internally. This is not sufficient to generate a usable API doc, and so this module exists to bridge that gap.
+In the [RESTful API](https://github.com/travetto/travetto/tree/main/module/rest#readme "Declarative api for RESTful APIs with support for the dependency injection module.") module, the controllers and endpoints can be described via decorators, comments, or typings. This only provides the general metadata internally. This is not sufficient to generate a usable API doc, and so this module exists to bridge that gap. 
 
 The module is provides an [OpenAPI](https://github.com/OAI/OpenAPI-Specification) v3.x representation of the API metadata provided via the [RESTful API](https://github.com/travetto/travetto/tree/main/module/rest#readme "Declarative api for RESTful APIs with support for the dependency injection module.") and [Schema](https://github.com/travetto/travetto/tree/main/module/schema#readme "Data type registry for runtime validation, reflection and binding.") modules.
 
@@ -23,9 +24,9 @@ All of the high level configurations can be found in the following structure:
 
 **Code: Config: OpenAPI Configuration**
 ```typescript
-import type { ServerObject, ContactObject, LicenseObject } from 'openapi3-ts/src/model/OpenApi';
+import type { ServerObject, ContactObject, LicenseObject } from 'openapi3-ts';
 
-import { Config, EnvVar } from '@travetto/config';
+import { Config } from '@travetto/config';
 import { path, RootIndex } from '@travetto/manifest';
 import { GlobalEnv } from '@travetto/base';
 import { Required } from '@travetto/schema';
@@ -70,7 +71,7 @@ export class ApiHostConfig {
   /**
    * OpenAPI Version
    */
-  openapi = '3.0.1';
+  openapi = '3.1.0';
 }
 
 /**
@@ -81,12 +82,10 @@ export class ApiSpecConfig {
   /**
    * Where to output file to
    */
-  @EnvVar('TRV_OPENAPI_OUTPUT')
   output: string = 'openapi.yml';
   /**
    * Should file be generated at runtime
    */
-  @EnvVar('TRV_OPENAPI_PERSIST')
   persist?: boolean;
   /**
    * Skip emitting all routes
@@ -98,14 +97,14 @@ export class ApiSpecConfig {
   exposeAllSchemas: boolean = false;
 
   async postConstruct(): Promise<void> {
-    this.output = path.toPosix(this.output);
+    this.output = path.resolve(this.output);
     if (!this.output || this.output === '-') {
       this.persist = false;
     } else {
       this.persist ??= GlobalEnv.dynamic;
     }
     if (this.persist) {
-      if (!/[.](json|ya?ml)$/.test(this.output)) { // Assume a folder
+      if (!/[.](json|ya?ml) $/.test(this.output)) { // Assume a folder
         this.output = path.resolve(this.output, 'openapi.yml');
       }
     }
@@ -114,20 +113,20 @@ export class ApiSpecConfig {
 ```
 
 ## Spec Generation
-The framework, when in watch mode, will generate the [OpenAPI](https://github.com/OAI/OpenAPI-Specification) specification in either [JSON](https://www.json.org) or [YAML](https://en.wikipedia.org/wiki/YAML). This module integrates with the file watching paradigm and can regenerate the openapi spec as changes to endpoints and models are made during development.  The output format is defined by the suffix of the output file, `.yaml` or `.json`.  
+The framework, when in watch mode, will generate the [OpenAPI](https://github.com/OAI/OpenAPI-Specification) specification in either [JSON](https://www.json.org) or [YAML](https://en.wikipedia.org/wiki/YAML). This module integrates with the file watching paradigm and can regenerate the openapi spec as changes to endpoints and models are made during development.  The output format is defined by the suffix of the output file, `.yaml` or `.json`.
 
 ## CLI - openapi:spec
-
 The module provides a command for the [Command Line Interface](https://github.com/travetto/travetto/tree/main/module/cli#readme "CLI infrastructure for Travetto framework") to allow scripting file generation.
 
 **Terminal: OpenAPI usage**
 ```bash
 $ trv openapi:spec --help
 
-Usage:  openapi:spec [options]
+Usage: openapi:spec [options]
 
 Options:
-  -o, --output <output>  Output files (default: "./openapi.yml")
+  -o, --output <string>  Output files
+  -m, --module <string>  Module to run for
   -h, --help             display help for command
 ```
 
@@ -136,26 +135,22 @@ The command will run your application, in non-server mode, to collect all the ro
 **Note**: The module supports generating the OpenAPI spec in real-time while listening for changes to routes and models.
 
 ## CLI - openapi:client
-
 The module provides a command for the [Command Line Interface](https://github.com/travetto/travetto/tree/main/module/cli#readme "CLI infrastructure for Travetto framework") to allow client generation from the API structure.
 
 **Terminal: OpenAPI usage**
 ```bash
 $ trv openapi:client --help
 
-Usage:  openapi:client [options] <format-or-preset>
+Usage: openapi:client [options] <format:string>
 
 Options:
-  -x, --extended-help                                  Show Extended Help
-  -a, --additional-properties <additional-properties>  Additional Properties (default: [])
-  -i, --input <input>                                  Input file (default:
-                                                       "./openapi.yml")
-  -o, --output <output>                                Output folder (default:
-                                                       "./api-client")
-  -d, --docker-image <docker-image>                    Docker Image to use (default:
-                                                       "arcsine/openapi-generator:latest")
-  -w, --watch                                          Watch for file changes
-  -h, --help                                           display help for command
+  -x, --extended-help                   Show Extended Help
+  -a, --additional-properties <string>  Additional Properties (default: [])
+  -i, --input <string>                  Input file (default: "./openapi.yml")
+  -o, --output <string>                 Output folder (default: "./api-client")
+  -d, --docker-image <string>           Docker Image to user (default: "arcsine/openapi-generator:latest")
+  -w, --watch                           Watch for file changes
+  -h, --help                            display help for command
 
 Available Presets
 ----------------------------------

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@travetto/openapi",
-  "version": "3.0.2",
+  "version": "3.1.0-rc.0",
   "description": "OpenAPI integration support for the Travetto framework",
   "keywords": [
     "rest",
@@ -26,14 +26,14 @@
     "directory": "module/openapi"
   },
   "dependencies": {
-    "@travetto/config": "^3.0.2",
-    "@travetto/rest": "^3.0.2",
-    "@travetto/schema": "^3.0.2",
-    "@travetto/yaml": "^3.0.2",
+    "@travetto/config": "^3.1.0-rc.0",
+    "@travetto/rest": "^3.1.0-rc.0",
+    "@travetto/schema": "^3.1.0-rc.0",
+    "@travetto/yaml": "^3.1.0-rc.0",
     "openapi3-ts": "^3.1.2"
   },
   "peerDependencies": {
-    "@travetto/cli": "^3.0.2"
+    "@travetto/cli": "^3.1.0-rc.0"
   },
   "peerDependenciesMeta": {
     "@travetto/cli": {

package/src/config.ts

@@ -1,11 +1,10 @@
-import type { ServerObject, ContactObject, LicenseObject } from 'openapi3-ts/src/model/OpenApi';
+import type { ServerObject, ContactObject, LicenseObject } from 'openapi3-ts';
 
-import { Config, EnvVar } from '@travetto/config';
+import { Config } from '@travetto/config';
 import { path, RootIndex } from '@travetto/manifest';
 import { GlobalEnv } from '@travetto/base';
 import { Required } from '@travetto/schema';
 
-
 /**
  * API Information, infers as much as possible from the package.json
  */
@@ -46,7 +45,7 @@ export class ApiHostConfig {
   /**
    * OpenAPI Version
    */
-  openapi = '3.0.1';
+  openapi = '3.1.0';
 }
 
 /**
@@ -57,12 +56,10 @@ export class ApiSpecConfig {
   /**
    * Where to output file to
    */
-  @EnvVar('TRV_OPENAPI_OUTPUT')
   output: string = 'openapi.yml';
   /**
    * Should file be generated at runtime
    */
-  @EnvVar('TRV_OPENAPI_PERSIST')
   persist?: boolean;
   /**
    * Skip emitting all routes
@@ -74,7 +71,7 @@ export class ApiSpecConfig {
   exposeAllSchemas: boolean = false;
 
   async postConstruct(): Promise<void> {
-    this.output = path.toPosix(this.output);
+    this.output = path.resolve(this.output);
     if (!this.output || this.output === '-') {
       this.persist = false;
     } else {

package/src/service.ts

@@ -65,7 +65,7 @@ export class OpenApiService {
         ...new SpecGenerator().generate(this.apiSpecConfig)
       };
     }
-    return this._spec;
+    return this._spec!;
   }
 
   /**

package/src/spec-generate.ts

@@ -2,7 +2,7 @@ import { Readable } from 'stream';
 import type {
   SchemaObject, SchemasObject, ParameterObject, OperationObject,
   RequestBodyObject, TagObject, PathsObject
-} from 'openapi3-ts/src/model/OpenApi';
+} from 'openapi3-ts';
 
 import { ControllerRegistry, EndpointConfig, ControllerConfig, ParamConfig, EndpointIOType } from '@travetto/rest';
 import { Class } from '@travetto/base';

package/support/bin/help.ts

@@ -0,0 +1,57 @@
+import fs from 'fs/promises';
+
+import { path, RootIndex } from '@travetto/manifest';
+import { cliTpl } from '@travetto/cli';
+import { OpenApiClientPresets } from './presets';
+import { ExecUtil } from '@travetto/base';
+
+/**
+ * Help utility for openapi client command
+ */
+export class OpenApiClientHelp {
+
+  static async getListOfFormats(dockerImage: string): Promise<string[]> {
+    const formatCache = path.resolve(RootIndex.manifest.workspacePath, RootIndex.manifest.toolFolder, 'trv-openapi-formats.json');
+    if (!await fs.stat(formatCache).catch(() => false)) {
+      const stdout = ExecUtil.spawn('docker', ['run', '--rm', dockerImage, 'list']);
+      const res = await stdout.result;
+      const lines = res.stdout
+        .split('DOCUMENTATION')[0]
+        .trim()
+        .split(/\n/g)
+        .filter(x => /^\s+-/.test(x) && !/\((beta|experimental)\)/.test(x))
+        .map(x => x.replace(/^\s+-\s+/, '').trim());
+
+      await fs.mkdir(path.dirname(formatCache), { recursive: true });
+      await fs.writeFile(formatCache, JSON.stringify([...lines.sort(),]));
+    }
+    const list: string[] = JSON.parse(await fs.readFile(formatCache, 'utf8'));
+    return list;
+  }
+
+  static async help(dockerImage: string, extendedHelp: boolean): Promise<string[]> {
+    const presets = await OpenApiClientPresets.getPresets();
+    const presetLen = Math.max(...Object.keys(presets).map(x => x.length));
+    const presetEntries = Object
+      .entries(presets)
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([k, [cmd, v]]) => [`@travetto/${k}`.padEnd(presetLen + 5), [cmd, OpenApiClientPresets.presetMap(v)]] as const);
+
+    const presetText = [
+      cliTpl`${{ subtitle: 'Available Presets' }}`,
+      '----------------------------------',
+      ...presetEntries.map(([k, [cmd, param]]) => cliTpl`* ${{ input: k }} -- ${{ identifier: cmd }} ${{ param }}`),
+    ];
+
+    if (extendedHelp) {
+      const formats = await this.getListOfFormats(dockerImage);
+      presetText.push(
+        '',
+        cliTpl`${{ subtitle: 'Available Formats' }}`,
+        '----------------------------------',
+        ...formats.map(x => cliTpl`* ${{ input: x }}`)
+      );
+    }
+    return presetText;
+  }
+}

package/support/bin/presets.ts

@@ -0,0 +1,22 @@
+import { FileResourceProvider } from '@travetto/base';
+
+/**
+ * Presets utility for openapi client command
+ */
+export class OpenApiClientPresets {
+
+  static #presets: Record<string, [string, object] | [string]>;
+  static #resources = new FileResourceProvider(['@travetto/openapi#support/resources']);
+
+  static async getPresets(): Promise<Record<string, [string, object] | [string]>> {
+    if (!this.#presets) {
+      const text = await this.#resources.read('presets.json');
+      this.#presets = JSON.parse(text);
+    }
+    return this.#presets;
+  }
+
+  static presetMap(prop?: object): string {
+    return !prop || Object.keys(prop).length === 0 ? '' : Object.entries(prop).map(([k, v]) => `${k}=${v}`).join(',');
+  }
+}

package/support/cli.openapi_client.ts

@@ -1,130 +1,68 @@
 import fs from 'fs/promises';
-import { existsSync, readFileSync, writeFileSync } from 'fs';
-import cp from 'child_process';
 
-import { path, RootIndex } from '@travetto/manifest';
-import { ExecUtil, FileResourceProvider } from '@travetto/base';
-import { CliCommand, cliTpl, OptionConfig, ListOptionConfig } from '@travetto/cli';
+import { path } from '@travetto/manifest';
+import { ExecUtil, ShutdownManager } from '@travetto/base';
+import { CliCommandShape, CliCommand, CliFlag } from '@travetto/cli';
+
+import { OpenApiClientHelp } from './bin/help';
+import { OpenApiClientPresets } from './bin/presets';
 
-type Options = {
-  extendedHelp: OptionConfig<boolean>;
-  props: ListOptionConfig<string>;
-  input: OptionConfig<string>;
-  output: OptionConfig<string>;
-  dockerImage: OptionConfig<string>;
-  watch: OptionConfig<boolean>;
-};
 /**
  * CLI for generating the cli client
  */
-export class OpenApiClientCommand extends CliCommand<Options> {
-  #presets: Record<string, [string, object] | [string]>;
-  name = 'openapi:client';
-  #resources = new FileResourceProvider(['@travetto/openapi#support/resources']);
-
-  async getPresets(): Promise<Record<string, [string, object] | [string]>> {
-    if (!this.#presets) {
-      const text = await this.#resources.read('presets.json');
-      this.#presets = JSON.parse(text);
-    }
-    return this.#presets;
-  }
-
-  presetMap(prop?: object): string {
-    return !prop || Object.keys(prop).length === 0 ? '' : Object.entries(prop).map(([k, v]) => `${k}=${v}`).join(',');
-  }
-
-  getListOfFormats(): string[] {
-    const formatCache = path.resolve(RootIndex.manifest.workspacePath, RootIndex.manifest.outputFolder, 'trv-openapi-formats.json');
-    if (!existsSync(formatCache)) {
-      const stdout = cp.execSync(`docker run --rm ${this.cmd.dockerImage} list`, { stdio: ['pipe', 'pipe'], encoding: 'utf8' }).trim();
-      const lines = stdout
-        .split('DOCUMENTATION')[0]
-        .trim()
-        .split(/\n/g)
-        .filter(x => /^\s+-/.test(x) && !/\((beta|experimental)\)/.test(x))
-        .map(x => x.replace(/^\s+-\s+/, '').trim());
-
-      writeFileSync(formatCache, JSON.stringify([...lines.sort(),]));
-    }
-    const list: string[] = JSON.parse(readFileSync(formatCache, 'utf8'));
-    return list;
-  }
-
-  getOptions(): Options {
-    return {
-      extendedHelp: this.boolOption({ name: 'extended-help', short: 'x', desc: 'Show Extended Help' }),
-      props: this.listOption({ name: 'additional-properties', short: 'a', desc: 'Additional Properties' }),
-      input: this.option({ desc: 'Input file', def: './openapi.yml', combine: v => path.resolve(v), completion: true }),
-      output: this.option({ desc: 'Output folder', def: './api-client', combine: v => path.resolve(v), completion: true }),
-      dockerImage: this.option({ desc: 'Docker Image to use', def: 'arcsine/openapi-generator:latest' }),
-      watch: this.boolOption({ desc: 'Watch for file changes' })
-    };
-  }
-
-  async help(): Promise<string> {
-    const presets = await this.getPresets();
-    const presetLen = Math.max(...Object.keys(presets).map(x => x.length));
-    const presetEntries = Object
-      .entries(presets)
-      .sort(([a], [b]) => a.localeCompare(b))
-      .map(([k, [cmd, v]]) => [`@travetto/${k}`.padEnd(presetLen + 5), [cmd, this.presetMap(v)]] as const);
-
-    const presetText = cliTpl`
-${{ subtitle: 'Available Presets' }}
-----------------------------------
-${presetEntries.map(([k, [cmd, param]]) => cliTpl`* ${{ input: k }} -- ${{ identifier: cmd }} ${{ param }}`).join('\n')}`;
-
-    const formatText = cliTpl`
-${{ subtitle: 'Available Formats' }}
-----------------------------------
-${this.getListOfFormats().map(x => cliTpl`* ${{ input: x }}`).join('\n')} `;
-
-    return this.cmd.extendedHelp ? `${presetText}\n${formatText}` : presetText;
-  }
-
-  getArgs(): string {
-    return '<format-or-preset>';
+@CliCommand()
+export class OpenApiClientCommand implements CliCommandShape {
+  @CliFlag({ desc: 'Show Extended Help', short: '-x' })
+  extendedHelp?: boolean;
+  @CliFlag({ desc: 'Additional Properties', short: '-a', name: '--additional-properties' })
+  props: string[] = [];
+  @CliFlag({ desc: 'Input file' })
+  input = './openapi.yml';
+  @CliFlag({ desc: 'Output folder' })
+  output = './api-client';
+  @CliFlag({ desc: 'Docker Image to user' })
+  dockerImage = 'arcsine/openapi-generator:latest';
+  @CliFlag({ desc: 'Watch for file changes' })
+  watch?: boolean;
+
+  async help(): Promise<string[]> {
+    return OpenApiClientHelp.help(this.dockerImage, this.extendedHelp ?? false);
   }
 
-  async action(format: string): Promise<void> {
-    if (!format) {
-      return this.showHelp('Format is required');
-    }
-
+  async main(format: string): Promise<void> {
     // Ensure its there
-    await fs.mkdir(this.cmd.output, { recursive: true });
+    await fs.mkdir(this.output, { recursive: true });
 
-    let propMap = Object.fromEntries(this.cmd.props?.map(p => p.split('=')) ?? []);
+    let propMap = Object.fromEntries(this.props?.map(p => p.split('=')) ?? []);
 
     if (format.startsWith('@travetto/')) {
       const key = format.split('@travetto/')[1];
-      const [fmt, props] = (await this.getPresets())[key];
+      const [fmt, props] = (await OpenApiClientPresets.getPresets())[key];
       format = fmt;
       propMap = { ...props, ...propMap };
     }
 
-    const propList = this.presetMap(propMap);
+    const propList = OpenApiClientPresets.presetMap(propMap);
 
     const args = [
       'run',
       '--user', `${process.geteuid?.()}:${process.getgid?.()}`,
-      '-v', `${this.cmd.output}:/workspace`,
-      '-v', `${path.dirname(this.cmd.input)}:/input`,
+      '-v', `${this.output}:/workspace`,
+      '-v', `${path.dirname(this.input)}:/input`,
       '-it',
       '--rm',
-      this.cmd.dockerImage,
+      this.dockerImage,
       'generate',
       '--skip-validate-spec',
       '--remove-operation-id-prefix',
       '-g', format,
       '-o', '/workspace',
-      '-i', `/input/${path.basename(this.cmd.input)}`,
-      ...(this.cmd.watch ? ['-w'] : []),
+      '-i', `/input/${path.basename(this.input)}`,
+      ...(this.watch ? ['-w'] : []),
       ...(propList ? ['--additional-properties', propList] : [])
     ];
 
     const { result } = ExecUtil.spawn('docker', args, { stdio: [0, 1, 2] });
-    await result.catch(err => this.exit(1));
+    await result.catch(err => ShutdownManager.exit(1));
   }
 }

package/support/cli.openapi_spec.ts

@@ -1,37 +1,37 @@
-import { CliCommand, OptionConfig } from '@travetto/cli';
-import { RootIndex } from '@travetto/manifest';
-import { ExecUtil, GlobalEnvConfig } from '@travetto/base';
+import fs from 'fs/promises';
 
-type Options = {
-  output: OptionConfig<string>;
-};
+import { CliCommandShape, CliCommand } from '@travetto/cli';
+import { GlobalEnvConfig } from '@travetto/base';
+import { RootRegistry } from '@travetto/registry';
+import { DependencyRegistry } from '@travetto/di';
+import { path } from '@travetto/manifest';
 
 /**
  * CLI for outputting the open api spec to a local file
  */
-export class OpenApiSpecCommand extends CliCommand<Options> {
-  name = 'openapi:spec';
+@CliCommand({ fields: ['module'] })
+export class OpenApiSpecCommand implements CliCommandShape {
 
-  getOptions(): Options {
-    return { output: this.option({ desc: 'Output files', def: './openapi.yml' }) };
-  }
+  /** Output files */
+  output?: string;
 
   envInit(): GlobalEnvConfig {
-    return {
-      debug: false,
-      set: { API_SPEC_OUTPUT: this.cmd.output }
-    };
+    return { debug: false };
   }
 
-  async action(): Promise<void> {
-    const result = await ExecUtil.worker(
-      RootIndex.resolveFileImport('@travetto/cli/support/cli.ts'),
-      ['main', '@travetto/openapi/support/bin/generate.ts'],
-      { env: { TRV_OPENAPI_OUTPUT: this.cmd.output, TRV_OPENAPI_PERSIST: '1' } }
-    ).message;
+  async main(): Promise<void> {
+    const { OpenApiService } = await import('../src/service.js');
+
+    await RootRegistry.init();
+
+    const instance = await DependencyRegistry.getInstance(OpenApiService);
+    const result = instance.spec;
 
-    if (this.cmd.output === '-' || !this.cmd.output) {
-      console.log!(result);
+    if (this.output === '-' || !this.output) {
+      console.log!(JSON.stringify(result, null, 2));
+    } else {
+      await fs.mkdir(path.dirname(this.output), { recursive: true });
+      await fs.writeFile(this.output, JSON.stringify(result, null, 2), 'utf8');
     }
   }
 }

package/support/bin/generate.ts

@@ -1,11 +0,0 @@
-import { DependencyRegistry } from '@travetto/di';
-import { RootRegistry } from '@travetto/registry';
-
-import { OpenApiService } from '../../src/service';
-
-export async function main(): Promise<unknown> {
-  await RootRegistry.init();
-
-  const instance = await DependencyRegistry.getInstance(OpenApiService);
-  return instance.spec;
-}