@travetto/openapi 8.0.0-alpha.9 → 8.0.0

package/README.md

@@ -26,12 +26,12 @@ All of the high level configurations can be found in the following structure:
 ```typescript
 import path from 'node:path';
 
-import type { ServerObject, ContactObject, LicenseObject } from 'openapi3-ts/oas31';
+import type { ContactObject, LicenseObject, ServerObject } from 'openapi3-ts/oas31';
 
 import { Config } from '@travetto/config';
+import { PostConstruct } from '@travetto/di';
 import { Runtime } from '@travetto/runtime';
 import { Required } from '@travetto/schema';
-import { PostConstruct } from '@travetto/di';
 
 /**
  * API Information, infers as much as possible from the package.json
@@ -105,7 +105,8 @@ export class ApiSpecConfig {
       this.persist ??= Runtime.localDevelopment;
     }
     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,43 +115,53 @@ 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.
+The command will load your application, in non-listening mode, to collect all the endpoints and model information, to produce the `openapi.yml`. Once produced, the code will store the output in the specified location.
 
-**Terminal: OpenAPI usage**
+**Terminal: Help for openapi:spec**
 ```bash
 $ trv openapi:spec --help
 
 Usage: openapi:spec [options]
 
+Description:
+  Generate the OpenAPI specification for the selected module.
+
+  The resulting JSON can be written to stdout or to a file path for use in
+  downstream tooling, CI publishing, and client generation pipelines.
+
 Options:
   -o, --output <string>  Output files
   -m, --module <module>  Module to run for
   --help                 display help for command
 ```
 
-The command will run your application, in non-server mode, to collect all the endpoints and model information, to produce the `openapi.yml`.  Once produced, the code will store the output in the specified location.
-
 **Note**: The module supports generating the OpenAPI spec in real-time while listening for changes to endpoints 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.
+Generate API clients from an OpenAPI specification using the generator image.
 
-**Terminal: OpenAPI usage**
+**Terminal: Help for openapi:client**
 ```bash
 $ trv openapi:client --help
 
 Usage: openapi:client [options] <format:string>
 
+Description:
+  Generate API clients from an OpenAPI specification using the generator image.
+
+  This command wraps OpenAPI Generator in Docker and writes generated client code
+  into the configured output folder.
+
 Options:
-  -x, --extended-help                   Show Extended Help (default: false)
-  -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: "openapitools/openapi-generator-cli:latest")
+  -x, --extended-help                   Show expanded generator help for all available formats/options. (default: false)
+  -a, --additional-properties <string>  Additional generator properties passed as comma-separated key/value pairs. (default: [])
+  -i, --input <string>                  Input OpenAPI document path. (default: "./openapi.yml")
+  -o, --output <string>                 Output directory for generated client sources. (default: "./api-client")
+  -d, --docker-image <string>           Docker image used to run OpenAPI Generator. (default: "openapitools/openapi-generator-cli:latest")
   --help                                display help for command
 ```
 
-This tool relies upon a custom build of [OpenAPI client generation tools](https://github.com/OpenAPITools/openapi-generator), which supports watching.  This allows for fast responsive client generation as the shape of the API changes.
+This tool relies upon a custom build of [OpenAPI client generation tools](https://github.com/OpenAPITools/openapi-generator), which supports watching. This allows for fast responsive client generation as the shape of the API changes.

package/__index__.ts

@@ -1,3 +1,3 @@
+export * from './src/config.ts';
 export * from './src/generate.ts';
 export * from './src/service.ts';
-export * from './src/config.ts';

package/package.json

@@ -1,40 +1,43 @@
 {
   "name": "@travetto/openapi",
-  "version": "8.0.0-alpha.9",
-  "type": "module",
+  "version": "8.0.0",
   "description": "OpenAPI integration support for the Travetto framework",
   "keywords": [
-    "web",
-    "travetto",
     "decorators",
     "schema",
-    "typescript"
+    "travetto",
+    "typescript",
+    "web"
   ],
   "homepage": "https://travetto.io",
   "license": "MIT",
   "author": {
-    "email": "travetto.framework@gmail.com",
-    "name": "Travetto Framework"
+    "name": "Travetto Framework",
+    "email": "travetto.framework@gmail.com"
+  },
+  "repository": {
+    "url": "git+https://github.com/travetto/travetto.git",
+    "directory": "module/openapi"
   },
   "files": [
     "__index__.ts",
     "src",
     "support"
   ],
+  "type": "module",
   "main": "__index__.ts",
-  "repository": {
-    "url": "git+https://github.com/travetto/travetto.git",
-    "directory": "module/openapi"
+  "publishConfig": {
+    "access": "public"
   },
   "dependencies": {
-    "@travetto/config": "^8.0.0-alpha.8",
-    "@travetto/schema": "^8.0.0-alpha.8",
-    "@travetto/web": "^8.0.0-alpha.9",
-    "openapi3-ts": "^4.5.0",
-    "yaml": "^2.8.2"
+    "@travetto/config": "^8.0.0",
+    "@travetto/schema": "^8.0.0",
+    "@travetto/web": "^8.0.0",
+    "openapi3-ts": "^4.6.1",
+    "yaml": "^2.9.0"
   },
   "peerDependencies": {
-    "@travetto/cli": "^8.0.0-alpha.13"
+    "@travetto/cli": "^8.0.0"
   },
   "peerDependenciesMeta": {
     "@travetto/cli": {
@@ -43,8 +46,5 @@
   },
   "travetto": {
     "displayName": "OpenAPI Specification"
-  },
-  "publishConfig": {
-    "access": "public"
   }
 }

package/src/config.ts

@@ -1,11 +1,11 @@
 import path from 'node:path';
 
-import type { ServerObject, ContactObject, LicenseObject } from 'openapi3-ts/oas31';
+import type { ContactObject, LicenseObject, ServerObject } from 'openapi3-ts/oas31';
 
 import { Config } from '@travetto/config';
+import { PostConstruct } from '@travetto/di';
 import { Runtime } from '@travetto/runtime';
 import { Required } from '@travetto/schema';
-import { PostConstruct } from '@travetto/di';
 
 /**
  * API Information, infers as much as possible from the package.json
@@ -79,9 +79,10 @@ export class ApiSpecConfig {
       this.persist ??= Runtime.localDevelopment;
     }
     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');
       }
     }
   }
-}
+}

package/src/controller.ts

@@ -1,8 +1,8 @@
 import { stringify } from 'yaml';
 
-import { ConfigureInterceptor, Controller, CorsInterceptor, Get, SetHeaders } from '@travetto/web';
 import { Inject } from '@travetto/di';
 import { IsPrivate } from '@travetto/schema';
+import { ConfigureInterceptor, Controller, CorsInterceptor, Get, SetHeaders } from '@travetto/web';
 
 import type { OpenApiService } from './service.ts';
 
@@ -13,7 +13,6 @@ import type { OpenApiService } from './service.ts';
 @Controller('/')
 @ConfigureInterceptor(CorsInterceptor, { origins: ['*'] })
 export class OpenApiController {
-
   @Inject()
   service: OpenApiService;
 
@@ -27,4 +26,4 @@ export class OpenApiController {
   async getYmlSpec(): Promise<string> {
     return stringify(await this.service.getSpec()); // Force output to be simple
   }
-}
+}

package/src/generate.ts

@@ -1,14 +1,31 @@
 import type {
-  SchemaObject, SchemasObject, ParameterObject, OperationObject,
-  RequestBodyObject, TagObject, PathsObject, PathItemObject
+  OperationObject,
+  ParameterObject,
+  PathItemObject,
+  PathsObject,
+  RequestBodyObject,
+  SchemaObject,
+  SchemasObject,
+  TagObject
 } from 'openapi3-ts/oas31';
 
-import { type EndpointConfig, type ControllerConfig, type EndpointParameterConfig, type ControllerVisitor, HTTP_METHODS } from '@travetto/web';
-import { RuntimeError, castTo, type Class, describeFunction } from '@travetto/runtime';
+import { type Class, castTo, describeFunction, RuntimeError } from '@travetto/runtime';
 import {
-  type SchemaFieldConfig, type SchemaClassConfig, SchemaNameResolver,
-  type SchemaInputConfig, SchemaRegistryIndex, type SchemaBasicType, type SchemaParameterConfig
+  type SchemaBasicType,
+  type SchemaClassConfig,
+  type SchemaFieldConfig,
+  type SchemaInputConfig,
+  SchemaNameResolver,
+  type SchemaParameterConfig,
+  SchemaRegistryIndex
 } from '@travetto/schema';
+import {
+  type ControllerConfig,
+  type ControllerVisitor,
+  type EndpointConfig,
+  type EndpointParameterConfig,
+  HTTP_METHODS
+} from '@travetto/web';
 
 import type { ApiSpecConfig } from './config.ts';
 
@@ -45,7 +62,12 @@ export class OpenapiVisitor implements ControllerVisitor<GeneratedSpec> {
   /**
    * Convert schema to a set of dotted parameters
    */
-  #schemaToDotParams(location: 'query' | 'header', input: SchemaInputConfig, prefix: string = '', rootField: SchemaInputConfig = input): ParameterObject[] {
+  #schemaToDotParams(
+    location: 'query' | 'header',
+    input: SchemaInputConfig,
+    prefix: string = '',
+    rootField: SchemaInputConfig = input
+  ): ParameterObject[] {
     if (!SchemaRegistryIndex.has(input.type)) {
       throw new RuntimeError(`Unknown class, not registered as a schema: ${input.type.Ⲑid}`);
     }
@@ -55,17 +77,19 @@ export class OpenapiVisitor implements ControllerVisitor<GeneratedSpec> {
     for (const sub of Object.values(fields)) {
       const name = sub.name;
       if (SchemaRegistryIndex.has(sub.type)) {
-        const suffix = (sub.array) ? '[]' : '';
+        const suffix = sub.array ? '[]' : '';
         params.push(...this.#schemaToDotParams(location, sub, prefix ? `${prefix}.${name}${suffix}` : `${name}${suffix}.`, rootField));
       } else {
         params.push({
           name: `${prefix}${name}`,
           description: sub.description,
-          schema: sub.array ? {
-            type: 'array',
-            ...this.#getType(sub)
-          } : this.#getType(sub),
-          required: (rootField?.required?.active !== false && sub.required?.active !== false),
+          schema: sub.array
+            ? {
+                type: 'array',
+                ...this.#getType(sub)
+              }
+            : this.#getType(sub),
+          required: rootField?.required?.active !== false && sub.required?.active !== false,
           in: location
         });
       }
@@ -77,7 +101,7 @@ export class OpenapiVisitor implements ControllerVisitor<GeneratedSpec> {
    * Get the type for a given class
    */
   #getType(inputOrClass: SchemaInputConfig | Class): Record<string, unknown> {
-    let field: { type: Class, precision?: [number, number | undefined] };
+    let field: { type: Class; precision?: [number, number | undefined] };
     if (!isInputConfig(inputOrClass)) {
       field = { type: inputOrClass };
     } else {
@@ -92,7 +116,9 @@ export class OpenapiVisitor implements ControllerVisitor<GeneratedSpec> {
       out.$ref = `${DEFINITION}/${id}`;
     } else {
       switch (field.type) {
-        case String: out.type = 'string'; break;
+        case String:
+          out.type = 'string';
+          break;
         case castTo(BigInt):
           out.type = 'integer';
           out.format = 'int64';
@@ -110,7 +136,9 @@ export class OpenapiVisitor implements ControllerVisitor<GeneratedSpec> {
           out.format = 'date-time';
           out.type = 'string';
           break;
-        case Boolean: out.type = 'boolean'; break;
+        case Boolean:
+          out.type = 'boolean';
+          break;
         default:
           out.type = 'object';
           break;
@@ -244,7 +272,7 @@ export class OpenapiVisitor implements ControllerVisitor<GeneratedSpec> {
     } else if (body.binary) {
       return {
         content: {
-          [mime ?? 'application/octet-stream']: { schema: { type: 'string', format: 'binary' } },
+          [mime ?? 'application/octet-stream']: { schema: { type: 'string', format: 'binary' } }
         },
         description: 'Raw binary data'
       };
@@ -266,11 +294,11 @@ export class OpenapiVisitor implements ControllerVisitor<GeneratedSpec> {
   /**
    * Process endpoint parameter
    */
-  #processEndpointParam(endpoint: EndpointConfig, param: EndpointParameterConfig, input: SchemaParameterConfig): (
-    { requestBody: RequestBodyObject } |
-    { parameters: ParameterObject[] } |
-    undefined
-  ) {
+  #processEndpointParam(
+    endpoint: EndpointConfig,
+    param: EndpointParameterConfig,
+    input: SchemaParameterConfig
+  ): { requestBody: RequestBodyObject } | { parameters: ParameterObject[] } | undefined {
     const complex = input.type && SchemaRegistryIndex.has(input.type);
 
     if (param.location) {
@@ -360,17 +388,11 @@ export class OpenapiVisitor implements ControllerVisitor<GeneratedSpec> {
       paths: Object.fromEntries(
         Object.entries(this.#paths)
           .toSorted(([a], [b]) => a.localeCompare(b))
-          .map(([key, value]) => [key, Object.fromEntries(
-            Object.entries(value)
-              .toSorted(([a], [b]) => a.localeCompare(b))
-          )])
+          .map(([key, value]) => [key, Object.fromEntries(Object.entries(value).toSorted(([a], [b]) => a.localeCompare(b)))])
       ),
       components: {
-        schemas: Object.fromEntries(
-          Object.entries(this.#schemas)
-            .toSorted(([a], [b]) => a.localeCompare(b))
-        )
+        schemas: Object.fromEntries(Object.entries(this.#schemas).toSorted(([a], [b]) => a.localeCompare(b)))
       }
     };
   }
-}
+}

package/src/service.ts

@@ -1,10 +1,11 @@
 import { createReadStream, existsSync } from 'node:fs';
+
 import type { OpenAPIObject } from 'openapi3-ts/oas31';
 import { stringify } from 'yaml';
 
+import { Inject, Injectable, PostConstruct } from '@travetto/di';
 import { ManifestFileUtil } from '@travetto/manifest';
 import { BinaryMetadataUtil, JSONUtil } from '@travetto/runtime';
-import { Injectable, Inject, PostConstruct } from '@travetto/di';
 import { ControllerVisitUtil, type WebConfig } from '@travetto/web';
 
 import type { ApiHostConfig, ApiInfoConfig, ApiSpecConfig } from './config.ts';
@@ -15,7 +16,6 @@ import { OpenapiVisitor } from './generate.ts';
  */
 @Injectable()
 export class OpenApiService {
-
   @Inject()
   apiHostConfig: ApiHostConfig;
 
@@ -60,7 +60,7 @@ export class OpenApiService {
       this.#spec = {
         ...this.apiHostConfig,
         info: { ...this.apiInfoConfig },
-        ...await ControllerVisitUtil.visit(new OpenapiVisitor(this.apiSpecConfig))
+        ...(await ControllerVisitUtil.visit(new OpenapiVisitor(this.apiSpecConfig)))
       };
     }
     return this.#spec!;
@@ -75,9 +75,7 @@ export class OpenApiService {
 
       const spec = await this.getSpec();
 
-      const output = this.apiSpecConfig.output.endsWith('.json') ?
-        JSONUtil.toUTF8Pretty(spec) :
-        stringify(spec);
+      const output = this.apiSpecConfig.output.endsWith('.json') ? JSONUtil.toUTF8Pretty(spec) : stringify(spec);
 
       if (existsSync(this.apiSpecConfig.output)) {
         const existing = await BinaryMetadataUtil.hash(createReadStream(this.apiSpecConfig.output));
@@ -94,4 +92,4 @@ export class OpenApiService {
       console.error('Unable to persist openapi spec', error);
     }
   }
-}
+}

package/support/bin/help.ts

@@ -1,18 +1,17 @@
-import fs from 'node:fs/promises';
 import { spawn } from 'node:child_process';
+import fs from 'node:fs/promises';
 import path from 'node:path';
 
-import { JSONUtil, ExecUtil, Runtime } from '@travetto/runtime';
 import { cliTpl } from '@travetto/cli';
+import { ExecUtil, JSONUtil, Runtime } from '@travetto/runtime';
 
 /**
  * Help utility for openapi client command
  */
 export class OpenApiClientHelp {
-
   static async getListOfFormats(dockerImage: string): Promise<string[]> {
     const formatCache = Runtime.toolPath('openapi-formats.json');
-    if (!await fs.stat(formatCache, { throwIfNoEntry: false })) {
+    if (!(await fs.stat(formatCache, { throwIfNoEntry: false }))) {
       const { stdout } = await ExecUtil.getResult(spawn('docker', ['run', '--rm', dockerImage, 'list']));
       const lines = stdout
         .split('DOCUMENTATION')[0]
@@ -22,7 +21,7 @@ export class OpenApiClientHelp {
         .map(line => line.replace(/^\s+-\s+/, '').trim());
 
       await fs.mkdir(path.dirname(formatCache), { recursive: true });
-      await fs.writeFile(formatCache, JSONUtil.toUTF8([...lines.toSorted(),]));
+      await fs.writeFile(formatCache, JSONUtil.toUTF8([...lines.toSorted()]));
     }
     return await fs.readFile(formatCache).then(JSONUtil.fromBinaryArray<string[]>);
   }
@@ -40,4 +39,4 @@ export class OpenApiClientHelp {
     }
     return help;
   }
-}
+}

package/support/cli.openapi_client.ts

@@ -1,27 +1,30 @@
-import path from 'node:path';
 import cp from 'node:child_process';
+import path from 'node:path';
 
-import { type CliCommandShape, CliCommand, CliFlag } from '@travetto/cli';
+import { CliCommand, type CliCommandShape, CliFlag } from '@travetto/cli';
 import { ExecUtil } from '@travetto/runtime';
 
 import { OpenApiClientHelp } from './bin/help.ts';
 
 /**
- * CLI for generating the cli client
+ * Generate API clients from an OpenAPI specification using the generator image.
+ *
+ * This command wraps OpenAPI Generator in Docker and writes generated client code
+ * into the configured output folder.
  */
 @CliCommand()
 export class OpenApiClientCommand implements CliCommandShape {
-  /** Show Extended Help */
+  /** Show expanded generator help for all available formats/options. */
   @CliFlag({ short: '-x' })
   extendedHelp: boolean = false;
-  /** Additional Properties */
+  /** Additional generator properties passed as comma-separated key/value pairs. */
   @CliFlag({ short: '-a', full: '--additional-properties' })
   properties: string[] = [];
-  /** Input file */
+  /** Input OpenAPI document path. */
   input = './openapi.yml';
-  /** Output folder */
+  /** Output directory for generated client sources. */
   output = './api-client';
-  /** Docker Image to user */
+  /** Docker image used to run OpenAPI Generator. */
   dockerImage = 'openapitools/openapi-generator-cli:latest';
 
   async help(): Promise<string[]> {
@@ -32,25 +35,35 @@ export class OpenApiClientCommand implements CliCommandShape {
     this.output = path.resolve(this.output);
     this.input = path.resolve(this.input);
 
-    const subProcess = cp.spawn('docker', [
-      'run',
-      '--rm',
-      '-i',
-      '-v', `${this.output}:/workspace`,
-      '-v', `${path.dirname(this.input)}:/input`,
-      '--user', `${process.geteuid?.() ?? 0}:${process.getgid?.() ?? 0}`,
-      this.dockerImage,
-      // Parameters
-      'generate',
-      '--skip-validate-spec',
-      '--remove-operation-id-prefix',
-      '-g', format,
-      '-o', '/workspace',
-      '-i', `/input/${path.basename(this.input)}`,
-      ...(this.properties.length ? ['--additional-properties', this.properties.join(',')] : [])
-    ], {
-      stdio: 'inherit'
-    });
+    const subProcess = cp.spawn(
+      'docker',
+      [
+        'run',
+        '--rm',
+        '-i',
+        '-v',
+        `${this.output}:/workspace`,
+        '-v',
+        `${path.dirname(this.input)}:/input`,
+        '--user',
+        `${process.geteuid?.() ?? 0}:${process.getgid?.() ?? 0}`,
+        this.dockerImage,
+        // Parameters
+        'generate',
+        '--skip-validate-spec',
+        '--remove-operation-id-prefix',
+        '-g',
+        format,
+        '-o',
+        '/workspace',
+        '-i',
+        `/input/${path.basename(this.input)}`,
+        ...(this.properties.length ? ['--additional-properties', this.properties.join(',')] : [])
+      ],
+      {
+        stdio: 'inherit'
+      }
+    );
 
     const result = await ExecUtil.getResult(subProcess);
 
@@ -58,4 +71,4 @@ export class OpenApiClientCommand implements CliCommandShape {
       process.exitCode = 1;
     }
   }
-}
+}

package/support/cli.openapi_spec.ts

@@ -1,17 +1,19 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 
-import { type CliCommandShape, CliCommand, CliModuleFlag } from '@travetto/cli';
-import { JSONUtil, Env } from '@travetto/runtime';
-import { Registry } from '@travetto/registry';
+import { CliCommand, type CliCommandShape, CliModuleFlag } from '@travetto/cli';
 import { DependencyRegistryIndex } from '@travetto/di';
+import { Registry } from '@travetto/registry';
+import { Env, JSONUtil } from '@travetto/runtime';
 
 /**
- * CLI for outputting the open api spec to a local file
+ * Generate the OpenAPI specification for the selected module.
+ *
+ * The resulting JSON can be written to stdout or to a file path for use in
+ * downstream tooling, CI publishing, and client generation pipelines.
  */
 @CliCommand()
 export class OpenApiSpecCommand implements CliCommandShape {
-
   /** Output files */
   output?: string;
 
@@ -38,4 +40,4 @@ export class OpenApiSpecCommand implements CliCommandShape {
       await fs.writeFile(this.output, text, 'utf8');
     }
   }
-}
+}