@travetto/openapi 6.0.3 → 7.0.0-rc.1

package/README.md

@@ -69,7 +69,7 @@ export class ApiHostConfig {
   /**
    * OpenAPI Version
    */
-  openapi = '3.0.0';
+  openapi = '3.1.0';
 }
 
 /**
@@ -142,7 +142,7 @@ $ trv openapi:client --help
 Usage: openapi:client [options] <format:string>
 
 Options:
-  -x, --extended-help                   Show Extended Help
+  -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")

package/package.json

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

package/src/config.ts

@@ -43,7 +43,7 @@ export class ApiHostConfig {
   /**
    * OpenAPI Version
    */
-  openapi = '3.0.0';
+  openapi = '3.1.0';
 }
 
 /**

package/src/controller.ts

@@ -1,14 +1,15 @@
 import { stringify } from 'yaml';
 
-import { ConfigureInterceptor, Controller, CorsInterceptor, Get, SetHeaders, Undocumented } from '@travetto/web';
+import { ConfigureInterceptor, Controller, CorsInterceptor, Get, SetHeaders } from '@travetto/web';
 import { Inject } from '@travetto/di';
+import { IsPrivate } from '@travetto/schema';
 
 import { OpenApiService } from './service.ts';
 
 /**
  * Basic controller for surfacing the api spec
  */
-@Undocumented()
+@IsPrivate()
 @Controller('/')
 @ConfigureInterceptor(CorsInterceptor, { origins: ['*'] })
 export class OpenApiController {

package/src/service.ts

@@ -3,8 +3,9 @@ import { stringify } from 'yaml';
 
 import { BinaryUtil } from '@travetto/runtime';
 import { Injectable, Inject } from '@travetto/di';
-import { ControllerRegistry, ControllerVisitUtil, WebConfig } from '@travetto/web';
-import { SchemaRegistry } from '@travetto/schema';
+import { ControllerRegistryIndex, ControllerVisitUtil, WebConfig } from '@travetto/web';
+import { SchemaRegistryIndex } from '@travetto/schema';
+import { Registry } from '@travetto/registry';
 
 import { ApiHostConfig, ApiInfoConfig, ApiSpecConfig } from './config.ts';
 import { OpenapiVisitor } from './spec-generate.ts';
@@ -43,8 +44,8 @@ export class OpenApiService {
    * Initialize after schemas are readied
    */
   async postConstruct(): Promise<void> {
-    ControllerRegistry.on(() => this.resetSpec());
-    SchemaRegistry.on(() => this.resetSpec());
+    Registry.onClassChange(() => this.resetSpec(), ControllerRegistryIndex);
+    Registry.onClassChange(() => this.resetSpec(), SchemaRegistryIndex);
 
     if (!this.apiHostConfig.servers && this.webConfig.baseUrl) {
       this.apiHostConfig.servers = [{ url: this.webConfig.baseUrl }];

package/src/spec-generate.ts

@@ -4,17 +4,16 @@ import type {
   RequestBodyObject, TagObject, PathsObject, PathItemObject
 } from 'openapi3-ts/oas31';
 
-import { EndpointConfig, ControllerConfig, EndpointParamConfig, EndpointIOType, ControllerVisitor, HTTP_METHODS } from '@travetto/web';
-import { Class, describeFunction } from '@travetto/runtime';
-import { SchemaRegistry, FieldConfig, ClassConfig, SchemaNameResolver } from '@travetto/schema';
+import { EndpointConfig, ControllerConfig, EndpointParameterConfig, ControllerVisitor, HTTP_METHODS } from '@travetto/web';
+import { AppError, Class, describeFunction } from '@travetto/runtime';
+import { SchemaFieldConfig, SchemaClassConfig, SchemaNameResolver, SchemaInputConfig, SchemaRegistryIndex, SchemaBasicType, SchemaParameterConfig } from '@travetto/schema';
 
 import { ApiSpecConfig } from './config.ts';
 
 const DEFINITION = '#/components/schemas';
 
-function isFieldConfig(val: object): val is FieldConfig {
-  return !!val && 'owner' in val && 'type' in val;
-}
+const isInputConfig = (val: object): val is SchemaInputConfig => !!val && 'owner' in val && 'type' in val;
+const isFieldConfig = (val: object): val is SchemaFieldConfig => isInputConfig(val) && 'name' in val;
 
 type GeneratedSpec = {
   tags: TagObject[];
@@ -44,26 +43,27 @@ export class OpenapiVisitor implements ControllerVisitor<GeneratedSpec> {
   /**
    * Convert schema to a set of dotted parameters
    */
-  #schemaToDotParams(location: 'query' | 'header', field: FieldConfig, prefix: string = '', rootField: FieldConfig = field): ParameterObject[] {
-    const viewConf = SchemaRegistry.has(field.type) && SchemaRegistry.getViewSchema(field.type, field.view);
-    const schemaConf = viewConf && viewConf.schema;
-    if (!schemaConf) {
-      throw new Error(`Unknown class, not registered as a schema: ${field.type.Ⲑid}`);
+  #schemaToDotParams(location: 'query' | 'header', input: SchemaInputConfig, prefix: string = '', rootField: SchemaInputConfig = input): ParameterObject[] {
+    if (!SchemaRegistryIndex.has(input.type)) {
+      throw new AppError(`Unknown class, not registered as a schema: ${input.type.Ⲑid}`);
     }
+
+    const fields = SchemaRegistryIndex.getFieldMap(input.type, input.view);
     const params: ParameterObject[] = [];
-    for (const sub of Object.values(schemaConf)) {
-      if (SchemaRegistry.has(sub.type) || SchemaRegistry.hasPending(sub.type)) {
+    for (const sub of Object.values(fields)) {
+      const name = sub.name.toString();
+      if (SchemaRegistryIndex.has(sub.type)) {
         const suffix = (sub.array) ? '[]' : '';
-        params.push(...this.#schemaToDotParams(location, sub, prefix ? `${prefix}.${sub.name}${suffix}` : `${sub.name}${suffix}.`, rootField));
+        params.push(...this.#schemaToDotParams(location, sub, prefix ? `${prefix}.${name}${suffix}` : `${name}${suffix}.`, rootField));
       } else {
         params.push({
-          name: `${prefix}${sub.name}`,
+          name: `${prefix}${name}`,
           description: sub.description,
           schema: sub.array ? {
             type: 'array',
             ...this.#getType(sub)
           } : this.#getType(sub),
-          required: !!(rootField?.required?.active && sub.required?.active),
+          required: (rootField?.required?.active !== false && sub.required?.active !== false),
           in: location
         });
       }
@@ -74,17 +74,17 @@ export class OpenapiVisitor implements ControllerVisitor<GeneratedSpec> {
   /**
    * Get the type for a given class
    */
-  #getType(fieldOrClass: FieldConfig | Class): Record<string, unknown> {
+  #getType(inputOrClass: SchemaInputConfig | Class): Record<string, unknown> {
     let field: { type: Class<unknown>, precision?: [number, number | undefined] };
-    if (!isFieldConfig(fieldOrClass)) {
-      field = { type: fieldOrClass };
+    if (!isInputConfig(inputOrClass)) {
+      field = { type: inputOrClass };
     } else {
-      field = fieldOrClass;
+      field = inputOrClass;
     }
     const out: Record<string, unknown> = {};
     // Handle nested types
-    if (SchemaRegistry.has(field.type)) {
-      const id = this.#nameResolver.getName(SchemaRegistry.get(field.type));
+    if (SchemaRegistryIndex.has(field.type)) {
+      const id = this.#nameResolver.getName(SchemaRegistryIndex.getConfig(field.type));
       // Exposing
       this.#schemas[id] = this.#allSchemas[id];
       out.$ref = `${DEFINITION}/${id}`;
@@ -130,40 +130,42 @@ export class OpenapiVisitor implements ControllerVisitor<GeneratedSpec> {
   /**
    * Process schema field
    */
-  #processSchemaField(field: FieldConfig, required: string[]): SchemaObject {
-    let prop: SchemaObject = this.#getType(field);
+  #processSchemaField(input: SchemaInputConfig, required: string[]): SchemaObject {
+    let prop: SchemaObject = this.#getType(input);
 
-    if (field.examples) {
-      prop.example = field.examples;
-    }
-    prop.description = field.description;
-    if (field.match) {
-      prop.pattern = field.match.re!.source;
+    if (input.examples) {
+      prop.example = input.examples;
     }
-    if (field.maxlength) {
-      prop.maxLength = field.maxlength.n;
+    prop.description = input.description;
+    if (input.match) {
+      prop.pattern = input.match.re!.source;
     }
-    if (field.minlength) {
-      prop.minLength = field.minlength.n;
+    if (input.maxlength) {
+      prop.maxLength = input.maxlength.n;
     }
-    if (field.min) {
-      prop.minimum = typeof field.min.n === 'number' ? field.min.n : field.min.n.getTime();
+    if (input.minlength) {
+      prop.minLength = input.minlength.n;
     }
-    if (field.max) {
-      prop.maximum = typeof field.max.n === 'number' ? field.max.n : field.max.n.getTime();
+    if (input.min) {
+      prop.minimum = typeof input.min.n === 'number' ? input.min.n : input.min.n.getTime();
     }
-    if (field.enum) {
-      prop.enum = field.enum.values;
+    if (input.max) {
+      prop.maximum = typeof input.max.n === 'number' ? input.max.n : input.max.n.getTime();
     }
-    if (field.required && field.required.active) {
-      required.push(field.name);
+    if (input.enum) {
+      prop.enum = input.enum.values;
     }
-    if (field.access === 'readonly') {
-      prop.readOnly = true;
-    } else if (field.access === 'writeonly') {
-      prop.writeOnly = true;
+    if (isFieldConfig(input)) {
+      if (input.required?.active !== false) {
+        required.push(input.name.toString());
+      }
+      if (input.access === 'readonly') {
+        prop.readOnly = true;
+      } else if (input.access === 'writeonly') {
+        prop.writeOnly = true;
+      }
     }
-    if (field.array) {
+    if (input.array) {
       prop = {
         type: 'array',
         items: prop
@@ -176,7 +178,7 @@ export class OpenapiVisitor implements ControllerVisitor<GeneratedSpec> {
   /**
    * Process schema class
    */
-  onSchema(type?: ClassConfig): void {
+  onSchema(type?: SchemaClassConfig): void {
     if (type === undefined) {
       return;
     }
@@ -185,33 +187,32 @@ export class OpenapiVisitor implements ControllerVisitor<GeneratedSpec> {
     const typeId = this.#nameResolver.getName(type);
 
     if (!this.#allSchemas[typeId]) {
-      const config = SchemaRegistry.get(cls);
+      const config = SchemaRegistryIndex.getConfig(cls);
       if (config) {
         this.#allSchemas[typeId] = {
-          title: config.title || config.description,
-          description: config.description || config.title,
-          example: config.examples
+          description: config.description,
+          examples: config.examples
         };
 
         const properties: Record<string, SchemaObject> = {};
-        const def = config.totalView;
+        const def = config;
         const required: string[] = [];
 
-        for (const fieldName of def.fields) {
-          if (SchemaRegistry.has(def.schema[fieldName].type)) {
-            this.onSchema(SchemaRegistry.get(def.schema[fieldName].type));
+        for (const fieldName of Object.keys(def.fields)) {
+          if (SchemaRegistryIndex.has(def.fields[fieldName].type)) {
+            this.onSchema(SchemaRegistryIndex.getConfig(def.fields[fieldName].type));
           }
-          properties[fieldName] = this.#processSchemaField(def.schema[fieldName], required);
+          properties[fieldName] = this.#processSchemaField(def.fields[fieldName], required);
         }
 
         const extra: Record<string, unknown> = {};
-        if (describeFunction(cls)?.abstract) {
-          const map = SchemaRegistry.getSubTypesForClass(cls);
+        if (config.discriminatedBase) {
+          const map = SchemaRegistryIndex.getDiscriminatedClasses(cls);
           if (map) {
             extra.oneOf = map
               .filter(x => !describeFunction(x)?.abstract)
               .map(c => {
-                this.onSchema(SchemaRegistry.get(c));
+                this.onSchema(SchemaRegistryIndex.getConfig(c));
                 return this.#getType(c);
               });
           }
@@ -223,7 +224,7 @@ export class OpenapiVisitor implements ControllerVisitor<GeneratedSpec> {
           ...extra
         });
       } else {
-        this.#allSchemas[typeId] = { title: typeId };
+        this.#allSchemas[typeId] = { description: typeId };
       }
     }
   }
@@ -231,20 +232,20 @@ export class OpenapiVisitor implements ControllerVisitor<GeneratedSpec> {
   /**
    * Standard payload structure
    */
-  #getEndpointBody(body?: EndpointIOType, mime?: string | null): RequestBodyObject {
-    if (!body) {
+  #getEndpointBody(body?: SchemaBasicType, mime?: string | null): RequestBodyObject {
+    if (!body || body.type === undefined) {
       return { content: {}, description: '' };
     } else if (body.type === Readable || body.type === Buffer) {
       return {
         content: {
-          [mime ?? 'application/octet-stream']: { schema: { type: 'string', format: 'binary' } }
+          [mime ?? 'application/octet-stream']: { schema: { type: 'string', format: 'binary' } },
         },
-        description: ''
+        description: 'Raw binary data'
       };
     } else {
-      const cls = SchemaRegistry.get(body.type);
-      const typeId = cls ? this.#nameResolver.getName(cls) : body.type.name;
-      const typeRef = cls ? this.#getType(body.type) : { type: body.type.name.toLowerCase() };
+      const schemaConfig = SchemaRegistryIndex.getOptionalConfig(body.type);
+      const typeId = schemaConfig ? this.#nameResolver.getName(schemaConfig) : body.type.name;
+      const typeRef = schemaConfig ? this.#getType(body.type) : { type: body.type.name.toLowerCase() };
       return {
         content: {
           [mime ?? 'application/json']: {
@@ -259,27 +260,28 @@ export class OpenapiVisitor implements ControllerVisitor<GeneratedSpec> {
   /**
    * Process endpoint parameter
    */
-  #processEndpointParam(ep: EndpointConfig, param: EndpointParamConfig, field: FieldConfig): (
+  #processEndpointParam(ep: EndpointConfig, param: EndpointParameterConfig, input: SchemaParameterConfig): (
     { requestBody: RequestBodyObject } |
     { parameters: ParameterObject[] } |
     undefined
   ) {
-    const complex = field.type && SchemaRegistry.has(field.type);
+    const complex = input.type && SchemaRegistryIndex.has(input.type);
+
     if (param.location) {
       if (param.location === 'body') {
         const acceptsMime = ep.finalizedResponseHeaders.get('accepts');
         return {
-          requestBody: field.specifiers?.includes('file') ? this.#buildUploadBody() : this.#getEndpointBody(field, acceptsMime)
+          requestBody: input.specifiers?.includes('file') ? this.#buildUploadBody() : this.#getEndpointBody(input, acceptsMime)
         };
       } else if (complex && (param.location === 'query' || param.location === 'header')) {
-        return { parameters: this.#schemaToDotParams(param.location, field, param.prefix ? `${param.prefix}.` : '') };
+        return { parameters: this.#schemaToDotParams(param.location, input, param.prefix ? `${param.prefix}.` : '') };
       } else {
         const epParam: ParameterObject = {
           in: param.location,
-          name: param.name || param.location,
-          description: field.description,
-          required: !!field.required?.active || false,
-          schema: field.array ? { type: 'array', items: this.#getType(field) } : this.#getType(field)
+          name: input.name ?? param.location,
+          description: input.description,
+          required: input.required?.active !== false,
+          schema: input.array ? { type: 'array', items: this.#getType(input) } : this.#getType(input)
         };
         return { parameters: [epParam] };
       }
@@ -296,23 +298,26 @@ export class OpenapiVisitor implements ControllerVisitor<GeneratedSpec> {
 
     const tagName = ctrl.externalName;
 
+    const schema = SchemaRegistryIndex.getMethodConfig(ep.class, ep.methodName);
+
     const op: OperationObject = {
       tags: [tagName],
       responses: {},
-      summary: ep.title,
-      description: ep.description || ep.title,
-      operationId: `${ep.class.name}_${ep.name}`,
+      summary: schema.description,
+      description: schema.description,
+      operationId: `${ep.class.name}_${ep.methodName.toString()}`,
       parameters: []
     };
 
     const contentTypeMime = ep.finalizedResponseHeaders.get('content-type');
-    const pConf = this.#getEndpointBody(ep.responseType, contentTypeMime);
+    const pConf = this.#getEndpointBody(schema.returnType, contentTypeMime);
     const code = Object.keys(pConf.content).length ? 200 : 201;
     op.responses![code] = pConf;
 
-    const schema = SchemaRegistry.getMethodSchema(ep.class, ep.name);
-    for (const field of schema) {
-      const result = this.#processEndpointParam(ep, ep.params[field.index!], field);
+    const methodSchema = SchemaRegistryIndex.getMethodConfig(ep.class, ep.methodName);
+
+    for (const param of methodSchema.parameters) {
+      const result = this.#processEndpointParam(ep, ep.parameters[param.index] ?? {}, param);
       if (result) {
         if ('parameters' in result) {
           (op.parameters ??= []).push(...result.parameters);
@@ -334,9 +339,10 @@ export class OpenapiVisitor implements ControllerVisitor<GeneratedSpec> {
     if (this.#config.skipEndpoints) {
       return;
     }
+    const classSchema = SchemaRegistryIndex.getConfig(controller.class);
     this.#tags.push({
       name: controller.externalName,
-      description: controller.description || controller.title
+      description: classSchema.description
     });
   }
 

package/support/cli.openapi_client.ts

@@ -11,19 +11,21 @@ import { OpenApiClientHelp } from './bin/help.ts';
  */
 @CliCommand()
 export class OpenApiClientCommand implements CliCommandShape {
-  @CliFlag({ desc: 'Show Extended Help', short: '-x' })
-  extendedHelp?: boolean;
-  @CliFlag({ desc: 'Additional Properties', short: '-a', name: '--additional-properties' })
+  /** Show Extended Help */
+  @CliFlag({ short: '-x' })
+  extendedHelp: boolean = false;
+  /** Additional Properties */
+  @CliFlag({ short: '-a', full: '--additional-properties' })
   props: string[] = [];
-  @CliFlag({ desc: 'Input file' })
+  /** Input file */
   input = './openapi.yml';
-  @CliFlag({ desc: 'Output folder' })
+  /** Output folder */
   output = './api-client';
-  @CliFlag({ desc: 'Docker Image to user' })
+  /** Docker Image to user */
   dockerImage = 'openapitools/openapi-generator-cli:latest';
 
   async help(): Promise<string[]> {
-    return OpenApiClientHelp.help(this.dockerImage, this.extendedHelp ?? false);
+    return OpenApiClientHelp.help(this.dockerImage, this.extendedHelp);
   }
 
   async main(format: string): Promise<void> {

package/support/cli.openapi_spec.ts

@@ -3,8 +3,8 @@ import path from 'node:path';
 
 import { CliCommandShape, CliCommand } from '@travetto/cli';
 import { Env } from '@travetto/runtime';
-import { RootRegistry } from '@travetto/registry';
-import { DependencyRegistry } from '@travetto/di';
+import { Registry } from '@travetto/registry';
+import { DependencyRegistryIndex } from '@travetto/di';
 
 /**
  * CLI for outputting the open api spec to a local file
@@ -22,10 +22,10 @@ export class OpenApiSpecCommand implements CliCommandShape {
   async main(): Promise<void> {
     const { OpenApiService } = await import('../src/service.ts');
 
-    await RootRegistry.init();
+    await Registry.init();
 
-    const instance = await DependencyRegistry.getInstance(OpenApiService);
-    const result = instance.getSpec();
+    const instance = await DependencyRegistryIndex.getInstance(OpenApiService);
+    const result = await instance.getSpec();
 
     if (this.output === '-' || !this.output) {
       console.log!(JSON.stringify(result, null, 2));