@travetto/openapi 2.1.3 → 2.2.0

package/README.md

@@ -20,7 +20,7 @@ All of the high level configurations can be found in the following structure:
 **Code: Config: OpenAPI Configuration**
 ```typescript
 import * as path from 'path';
-import * as fs from 'fs';
+import * as fs from 'fs/promises';
 import { ServerObject, ContactObject, LicenseObject } from 'openapi3-ts/src/model/OpenApi';
 
 import { Config } from '@travetto/config';
@@ -37,7 +37,7 @@ export class ApiInfoConfig {
   license: LicenseObject = { name: AppManifest.info.license! };
   termsOfService?: string;
   title: string = AppManifest.info.name;
-  version?: string = AppManifest.info.version;
+  version: string = AppManifest.info.version ?? '0.0.0';
 }
 
 /**
@@ -77,7 +77,7 @@ export class ApiSpecConfig {
    */
   exposeAllSchemas: boolean = false;
 
-  async postConstruct() {
+  async postConstruct(): Promise<void> {
     this.output = PathUtil.toUnix(this.output);
     if (!this.output || this.output === '-') {
       this.persist = false;
@@ -86,7 +86,7 @@ export class ApiSpecConfig {
       if (!/[.](json|ya?ml)$/.test(this.output)) { // Assume a folder
         this.output = PathUtil.resolveUnix(this.output, 'openapi.yml');
       }
-      await fs.promises.mkdir(path.dirname(this.output), { recursive: true });
+      await fs.mkdir(path.dirname(this.output), { recursive: true });
     }
   }
 }

package/bin/cli-openapi_client.ts

@@ -6,7 +6,7 @@ import { BasePlugin } from '@travetto/cli/src/plugin-base';
 import { AppCache, ExecUtil, PathUtil } from '@travetto/boot';
 import { color } from '@travetto/cli/src/color';
 
-const presets = JSON.parse(readFileSync(PathUtil.resolveUnix(__dirname, '..', 'resources', 'presets.json'), 'utf8')) as Record<string, [string, object] | [string]>;
+const presets: Record<string, [string, object] | [string]> = JSON.parse(readFileSync(PathUtil.resolveUnix(__dirname, '..', 'resources', 'presets.json'), 'utf8'));
 
 /**
  * CLI for generating the cli client
@@ -14,11 +14,11 @@ const presets = JSON.parse(readFileSync(PathUtil.resolveUnix(__dirname, '..', 'r
 export class OpenApiClientPlugin extends BasePlugin {
   name = 'openapi:client';
 
-  presetMap(prop?: object) {
+  presetMap(prop?: object): string {
     return !prop || Object.keys(prop).length === 0 ? '' : Object.entries(prop).map(([k, v]) => `${k}=${v}`).join(',');
   }
 
-  getListOfFormats() {
+  getListOfFormats(): string[] {
     const json = AppCache.getOrSet('openapi-formats.json', () => {
       const stdout = ExecUtil.execSync('docker', ['run', '--rm', this.cmd.dockerImage, 'list']);
       const lines = stdout
@@ -31,9 +31,11 @@ export class OpenApiClientPlugin extends BasePlugin {
         ...lines.sort(),
       ]);
     });
-    return JSON.parse(json) as string[];
+    const list: string[] = JSON.parse(json);
+    return list;
   }
 
+  // eslint-disable-next-line @typescript-eslint/explicit-function-return-type
   getOptions() {
     return {
       extendedHelp: this.boolOption({ name: 'extended-help', short: 'x', desc: 'Show Extended Help' }),
@@ -45,7 +47,7 @@ export class OpenApiClientPlugin extends BasePlugin {
     };
   }
 
-  help() {
+  help(): string {
     const presetLen = Math.max(...Object.keys(presets).map(x => x.length));
     const presetEntries = Object
       .entries(presets)
@@ -65,11 +67,11 @@ ${this.getListOfFormats().map(x => color`* ${{ input: x }}`).join('\n')} `;
     return this.cmd.extendedHelp ? `${presetText}\n${formatText}` : presetText;
   }
 
-  getArgs() {
+  getArgs(): string {
     return '[format-or-preset]';
   }
 
-  async action(format: string) {
+  async action(format: string): Promise<void> {
     if (!format) {
       this.showHelp(new Error('Format is required'));
     }
@@ -90,7 +92,7 @@ ${this.getListOfFormats().map(x => color`* ${{ input: x }}`).join('\n')} `;
 
     const args = [
       'run',
-      '--user', `${process.geteuid()}:${process.getgid()}`,
+      '--user', `${process.geteuid?.()}:${process.getgid?.()}`,
       '-v', `${this.cmd.output}:/workspace`,
       '-v', `${path.dirname(this.cmd.input)}:/input`,
       '-it',

package/bin/cli-openapi_spec.ts

@@ -8,18 +8,19 @@ import { EnvInit } from '@travetto/base/bin/init';
 export class OpenApiSpecPlugin extends BasePlugin {
   name = 'openapi:spec';
 
+  // eslint-disable-next-line @typescript-eslint/explicit-function-return-type
   getOptions() {
     return { output: this.option({ desc: 'Output files', def: './openapi.yml' }) };
   }
 
-  envInit() {
+  envInit(): void {
     EnvInit.init({
       debug: '0',
       set: { API_SPEC_OUTPUT: this.cmd.output }
     });
   }
 
-  async action() {
+  async action(): Promise<void> {
     const result = await ExecUtil.workerMain(require.resolve('./generate')).message;
 
     if (this.cmd.output === '-' || !this.cmd.output) {

package/bin/generate.ts

@@ -1,6 +1,6 @@
 import { ExecUtil } from '@travetto/boot';
 
-export async function main() {
+export async function main(): Promise<void> {
   const { PhaseManager } = await import('@travetto/base');
   await PhaseManager.run('init');
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@travetto/openapi",
   "displayName": "OpenAPI Specification",
-  "version": "2.1.3",
+  "version": "2.2.0",
   "description": "OpenAPI integration support for the travetto framework",
   "keywords": [
     "rest",
@@ -28,14 +28,14 @@
     "directory": "module/openapi"
   },
   "dependencies": {
-    "@travetto/config": "^2.1.3",
-    "@travetto/rest": "^2.1.3",
-    "@travetto/schema": "^2.1.3",
-    "@travetto/yaml": "^2.1.3",
+    "@travetto/config": "^2.2.0",
+    "@travetto/rest": "^2.2.0",
+    "@travetto/schema": "^2.2.0",
+    "@travetto/yaml": "^2.2.0",
     "openapi3-ts": "^2.0.2"
   },
   "optionalPeerDependencies": {
-    "@travetto/cli": "^2.1.2"
+    "@travetto/cli": "^2.2.0"
   },
   "publishConfig": {
     "access": "public"

package/src/config.ts

@@ -16,7 +16,7 @@ export class ApiInfoConfig {
   license: LicenseObject = { name: AppManifest.info.license! };
   termsOfService?: string;
   title: string = AppManifest.info.name;
-  version?: string = AppManifest.info.version;
+  version: string = AppManifest.info.version ?? '0.0.0';
 }
 
 /**
@@ -56,7 +56,7 @@ export class ApiSpecConfig {
    */
   exposeAllSchemas: boolean = false;
 
-  async postConstruct() {
+  async postConstruct(): Promise<void> {
     this.output = PathUtil.toUnix(this.output);
     if (!this.output || this.output === '-') {
       this.persist = false;

package/src/controller.ts

@@ -14,13 +14,13 @@ export class OpenApiController {
   service: OpenApiService;
 
   @Get('openapi.json')
-  async getSpec() {
-    return this.service.spec as object; // Force output to be simple
+  async getSpec(): Promise<object> {
+    return this.service.spec; // Force output to be simple
   }
 
   @Get(/openapi[.]ya?ml$/)
   @SetHeaders({ 'Content-Type': 'text/vnd.yaml' })
-  async getYmlSpec() {
+  async getYmlSpec(): Promise<string> {
     return YamlUtil.serialize(this.service.spec); // Force output to be simple
   }
 }

package/src/service.ts

@@ -32,7 +32,7 @@ export class OpenApiService {
   /**
    * Reset specification
    */
-  async resetSpec() {
+  async resetSpec(): Promise<void> {
     delete this._spec;
     if (this.apiSpecConfig.persist) {
       await this.persist();
@@ -42,7 +42,7 @@ export class OpenApiService {
   /**
    * Initialize after schemas are readied
    */
-  async postConstruct() {
+  async postConstruct(): Promise<void> {
     ControllerRegistry.on(() => this.resetSpec());
     SchemaRegistry.on(() => this.resetSpec());
 
@@ -62,7 +62,7 @@ export class OpenApiService {
         ...this.apiHostConfig,
         info: { ...this.apiInfoConfig },
         ...new SpecGenerator().generate(this.apiSpecConfig)
-      } as OpenAPIObject;
+      };
     }
     return this._spec;
   }
@@ -70,7 +70,7 @@ export class OpenApiService {
   /**
    * Persist to local file
    */
-  async persist() {
+  async persist(): Promise<void> {
     console.debug('Generating OpenAPI Spec', { output: this.apiSpecConfig.output });
 
     const output = this.apiSpecConfig.output.endsWith('.json') ?

package/src/spec-generate.ts

@@ -1,11 +1,11 @@
 import { Readable } from 'stream';
 import {
   SchemaObject, SchemasObject, ParameterObject, OperationObject,
-  RequestBodyObject, TagObject, PathItemObject
+  RequestBodyObject, TagObject, PathItemObject, OpenAPIObject
 } from 'openapi3-ts/src/model/OpenApi';
 
 import { ControllerRegistry, EndpointConfig, ControllerConfig, ParamConfig, EndpointIOType } from '@travetto/rest';
-import { Class, Util } from '@travetto/base';
+import { Class } from '@travetto/base';
 import { SchemaRegistry, FieldConfig } from '@travetto/schema';
 import { AllViewⲐ } from '@travetto/schema/src/internal/types';
 
@@ -14,6 +14,10 @@ import { OpenApiController } from './controller';
 
 const DEFINITION = '#/components/schemas';
 
+function isFieldConfig(val: object): val is FieldConfig {
+  return !!val && 'owner' in val && 'type' in val;
+}
+
 /**
  * Spec generation utilities
  */
@@ -27,7 +31,7 @@ export class SpecGenerator {
    * Get type id
    * @param cls
    */
-  #getTypeId(cls: Class) {
+  #getTypeId(cls: Class): string {
     return cls.name?.replace('ᚕsyn', '');
   }
 
@@ -35,7 +39,7 @@ export class SpecGenerator {
    * Get tag name
    * @param cls
    */
-  #getTypeTag(cls: Class) {
+  #getTypeTag(cls: Class): string {
     return cls.name.replace(/(Rest|Controller)$/, '');
   }
 
@@ -84,11 +88,13 @@ export class SpecGenerator {
   /**
    * Get the type for a given class
    */
-  #getType(field: FieldConfig | Class) {
-    if (!Util.isPlainObject(field)) {
-      field = { type: field } as FieldConfig;
+  #getType(fieldOrClass: FieldConfig | Class): Record<string, unknown> {
+    let field: { type: Class<unknown>, precision?: [number, number | undefined] };
+    if (!isFieldConfig(fieldOrClass)) {
+      field = { type: fieldOrClass };
+    } else {
+      field = fieldOrClass;
     }
-    field = field as FieldConfig;
     const out: Record<string, unknown> = {};
     // Handle nested types
     if (SchemaRegistry.has(field.type)) {
@@ -138,7 +144,7 @@ export class SpecGenerator {
   /**
    * Process schema field
    */
-  #processSchemaField(field: FieldConfig, required: string[]) {
+  #processSchemaField(field: FieldConfig, required: string[]): SchemaObject {
     let prop: SchemaObject = this.#getType(field);
 
     if (field.examples) {
@@ -155,10 +161,10 @@ export class SpecGenerator {
       prop.minLength = field.minlength.n;
     }
     if (field.min) {
-      prop.minimum = field.min.n as number;
+      prop.minimum = typeof field.min.n === 'number' ? field.min.n : field.min.n.getTime();
     }
     if (field.max) {
-      prop.maximum = field.max.n as number;
+      prop.maximum = typeof field.max.n === 'number' ? field.max.n : field.max.n.getTime();
     }
     if (field.enum) {
       prop.enum = field.enum.values;
@@ -184,7 +190,7 @@ export class SpecGenerator {
   /**
    * Process schema class
    */
-  #processSchema(type?: string | Class) {
+  #processSchema(type?: string | Class): string | undefined {
     if (type === undefined || typeof type === 'string') {
       return undefined;
     }
@@ -231,13 +237,13 @@ export class SpecGenerator {
     } else if (body.type === Readable || body.type === Buffer) {
       return {
         content: {
-          [mime ?? 'application/octect-stream']: { type: 'string', format: 'binary' }
+          [mime ?? 'application/octet-stream']: { type: 'string', format: 'binary' }
         },
         description: ''
       };
     } else {
       const typeId = this.#getTypeId(body.type);
-      const typeRef = SchemaRegistry.has(body.type) ? this.#getType(body.type) : { type: body.type.name.toLowerCase() as 'string' };
+      const typeRef = SchemaRegistry.has(body.type) ? this.#getType(body.type) : { type: body.type.name.toLowerCase() };
       return {
         content: {
           [mime ?? 'application/json']: {
@@ -252,7 +258,11 @@ export class SpecGenerator {
   /**
    * Process endpoint parameter
    */
-  #processEndpointParam(ep: EndpointConfig, param: ParamConfig, field: FieldConfig) {
+  #processEndpointParam(ep: EndpointConfig, param: ParamConfig, field: FieldConfig): (
+    { requestBody: RequestBodyObject } |
+    { parameters: ParameterObject[] } |
+    undefined
+  ) {
     if (param.location) {
       if (param.location === 'body') {
         return {
@@ -262,7 +272,7 @@ export class SpecGenerator {
         return { parameters: this.#schemaToDotParams(param.location, field) };
       } else if (param.location !== 'context') {
         const epParam: ParameterObject = {
-          in: param.location as 'path',
+          in: param.location,
           name: param.name || param.location,
           description: field.description,
           required: !!field.required?.active || false,
@@ -278,7 +288,7 @@ export class SpecGenerator {
   /**
    * Process controller endpoint
    */
-  processEndpoint(ctrl: ControllerConfig, ep: EndpointConfig) {
+  processEndpoint(ctrl: ControllerConfig, ep: EndpointConfig): void {
 
     const tagName = ctrl.class.name.replace(/(Rest|Controller)$/, '');
 
@@ -298,14 +308,17 @@ export class SpecGenerator {
     const schema = SchemaRegistry.getMethodSchema(ep.class, ep.handlerName);
     for (const field of schema) {
       const res = this.#processEndpointParam(ep, ep.params[field.index!], field);
-      if (res?.parameters) {
-        (op.parameters ??= []).push(...res.parameters);
+      if (res) {
+        if ('parameters' in res) {
+          (op.parameters ??= []).push(...res.parameters);
+        } else {
+          op.requestBody ??= res.requestBody;
+        }
       }
-      op.requestBody ??= res?.requestBody;
     }
 
     const epPath = (
-      !ep.path ? '/' : typeof ep.path === 'string' ? (ep.path as string) : (ep.path as RegExp).source
+      !ep.path ? '/' : typeof ep.path === 'string' ? ep.path : ep.path.source
     ).replace(/:([A-Za-z0-9_]+)\b/g, (__, param) => `{${param}}`);
 
     const key = `${ctrl.basePath}${epPath}`.replace(/[\/]+/g, '/');
@@ -324,7 +337,7 @@ export class SpecGenerator {
   /**
    * Process each controller
    */
-  processController(cls: Class) {
+  processController(cls: Class): void {
     const ctrl = ControllerRegistry.get(cls);
 
     this.#tags.push({
@@ -340,7 +353,7 @@ export class SpecGenerator {
   /**
    * Generate full specification
    */
-  generate(config: Partial<ApiSpecConfig> = {}) {
+  generate(config: Partial<ApiSpecConfig> = {}): Pick<OpenAPIObject, 'tags' | 'paths' | 'components'> {
 
     for (const cls of ControllerRegistry.getClasses()) {
       for (const ep of ControllerRegistry.get(cls).endpoints) {