@travetto/openapi 8.0.0-alpha.22 → 8.0.0-alpha.23

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,10 +115,10 @@ 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 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.
+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: Help for openapi:spec**
 ```bash
@@ -163,4 +164,4 @@ Options:
   --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,6 +1,6 @@
 {
   "name": "@travetto/openapi",
-  "version": "8.0.0-alpha.22",
+  "version": "8.0.0-alpha.23",
   "type": "module",
   "description": "OpenAPI integration support for the Travetto framework",
   "keywords": [
@@ -27,14 +27,14 @@
     "directory": "module/openapi"
   },
   "dependencies": {
-    "@travetto/config": "^8.0.0-alpha.21",
-    "@travetto/schema": "^8.0.0-alpha.21",
-    "@travetto/web": "^8.0.0-alpha.22",
+    "@travetto/config": "^8.0.0-alpha.22",
+    "@travetto/schema": "^8.0.0-alpha.22",
+    "@travetto/web": "^8.0.0-alpha.23",
     "openapi3-ts": "^4.6.0",
     "yaml": "^2.9.0"
   },
   "peerDependencies": {
-    "@travetto/cli": "^8.0.0-alpha.27"
+    "@travetto/cli": "^8.0.0-alpha.28"
   },
   "peerDependenciesMeta": {
     "@travetto/cli": {

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,7 +1,7 @@
-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';
@@ -35,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);
 
@@ -61,4 +71,4 @@ export class OpenApiClientCommand implements CliCommandShape {
       process.exitCode = 1;
     }
   }
-}
+}

package/support/cli.openapi_spec.ts

@@ -1,10 +1,10 @@
 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';
 
 /**
  * Generate the OpenAPI specification for the selected module.
@@ -14,7 +14,6 @@ import { DependencyRegistryIndex } from '@travetto/di';
  */
 @CliCommand()
 export class OpenApiSpecCommand implements CliCommandShape {
-
   /** Output files */
   output?: string;
 
@@ -41,4 +40,4 @@ export class OpenApiSpecCommand implements CliCommandShape {
       await fs.writeFile(this.output, text, 'utf8');
     }
   }
-}
+}