@travetto/openapi 6.0.0-rc.1 → 6.0.0-rc.3

package/README.md

@@ -13,9 +13,9 @@ 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 [Web API](https://github.com/travetto/travetto/tree/main/module/web#readme "Declarative api for Web Applications with support for the dependency injection.") 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.
+The module is provides an [OpenAPI](https://github.com/OAI/OpenAPI-Specification) v3.x representation of the API metadata provided via the [Web API](https://github.com/travetto/travetto/tree/main/module/web#readme "Declarative api for Web Applications with support for the dependency injection.") and [Schema](https://github.com/travetto/travetto/tree/main/module/schema#readme "Data type registry for runtime validation, reflection and binding.") modules.
 
 ## Configuration
 By installing the dependency, the [OpenAPI](https://github.com/OAI/OpenAPI-Specification) endpoint is automatically generated and exposed at the root of the application as `/openapi.yml` or `/openapi.json` (by default). 
@@ -58,7 +58,7 @@ export class ApiInfoConfig {
 }
 
 /**
- * The API host, infers from rest host configuration
+ * The API host, infers from web host configuration
  */
 @Config('api.host')
 export class ApiHostConfig {
@@ -86,9 +86,9 @@ export class ApiSpecConfig {
    */
   persist?: boolean;
   /**
-   * Skip emitting all routes
+   * Skip emitting all endpoints
    */
-  skipRoutes: boolean = false;
+  skipEndpoints: boolean = false;
   /**
    * Expose all schemas, even if not referenced
    */
@@ -128,9 +128,9 @@ Options:
   -h, --help             display help for command
 ```
 
-The command will run your application, in non-server mode, to collect all the routes and model information, to produce the `openapi.yml`.  Once produced, the code will store the output in the specified location.
+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 routes and models.
+**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.

package/__index__.ts

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

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@travetto/openapi",
-  "version": "6.0.0-rc.1",
+  "version": "6.0.0-rc.3",
   "description": "OpenAPI integration support for the Travetto framework",
   "keywords": [
-    "rest",
+    "web",
     "travetto",
     "decorators",
     "schema",
@@ -26,14 +26,14 @@
     "directory": "module/openapi"
   },
   "dependencies": {
-    "@travetto/config": "^6.0.0-rc.1",
-    "@travetto/rest": "^6.0.0-rc.1",
-    "@travetto/schema": "^6.0.0-rc.1",
+    "@travetto/config": "^6.0.0-rc.2",
+    "@travetto/schema": "^6.0.0-rc.2",
+    "@travetto/web": "^6.0.0-rc.3",
     "openapi3-ts": "^4.4.0",
-    "yaml": "^2.7.0"
+    "yaml": "^2.7.1"
   },
   "peerDependencies": {
-    "@travetto/cli": "^6.0.0-rc.1"
+    "@travetto/cli": "^6.0.0-rc.3"
   },
   "peerDependenciesMeta": {
     "@travetto/cli": {

package/src/config.ts

@@ -32,7 +32,7 @@ export class ApiInfoConfig {
 }
 
 /**
- * The API host, infers from rest host configuration
+ * The API host, infers from web host configuration
  */
 @Config('api.host')
 export class ApiHostConfig {
@@ -60,9 +60,9 @@ export class ApiSpecConfig {
    */
   persist?: boolean;
   /**
-   * Skip emitting all routes
+   * Skip emitting all endpoints
    */
-  skipRoutes: boolean = false;
+  skipEndpoints: boolean = false;
   /**
    * Expose all schemas, even if not referenced
    */

package/src/controller.ts

@@ -1,9 +1,9 @@
 import { stringify } from 'yaml';
 
-import { ConfigureInterceptor, Controller, CorsInterceptor, Get, SetHeaders, Undocumented } from '@travetto/rest';
+import { ConfigureInterceptor, Controller, CorsInterceptor, Get, SetHeaders, Undocumented } from '@travetto/web';
 import { Inject } from '@travetto/di';
 
-import { OpenApiService } from './service';
+import { OpenApiService } from './service.ts';
 
 /**
  * Basic controller for surfacing the api spec

package/src/service.ts

@@ -3,11 +3,11 @@ import { stringify } from 'yaml';
 
 import { BinaryUtil } from '@travetto/runtime';
 import { Injectable, Inject } from '@travetto/di';
-import { ControllerRegistry, ControllerVisitUtil, RestConfig } from '@travetto/rest';
+import { ControllerRegistry, ControllerVisitUtil, WebConfig } from '@travetto/web';
 import { SchemaRegistry } from '@travetto/schema';
 
-import { ApiHostConfig, ApiInfoConfig, ApiSpecConfig } from './config';
-import { OpenapiVisitor } from './spec-generate';
+import { ApiHostConfig, ApiInfoConfig, ApiSpecConfig } from './config.ts';
+import { OpenapiVisitor } from './spec-generate.ts';
 
 /**
  * Open API generation service
@@ -25,7 +25,7 @@ export class OpenApiService {
   apiSpecConfig: ApiSpecConfig;
 
   @Inject()
-  restConfig: RestConfig;
+  webConfig: WebConfig;
 
   #spec: OpenAPIObject | undefined;
 
@@ -46,8 +46,8 @@ export class OpenApiService {
     ControllerRegistry.on(() => this.resetSpec());
     SchemaRegistry.on(() => this.resetSpec());
 
-    if (!this.apiHostConfig.servers) {
-      this.apiHostConfig.servers = [{ url: this.restConfig.baseUrl }];
+    if (!this.apiHostConfig.servers && this.webConfig.baseUrl) {
+      this.apiHostConfig.servers = [{ url: this.webConfig.baseUrl }];
     }
 
     await this.resetSpec();

package/src/spec-generate.ts

@@ -4,12 +4,11 @@ import type {
   RequestBodyObject, TagObject, PathsObject, PathItemObject
 } from 'openapi3-ts/oas31';
 
-import { EndpointConfig, ControllerConfig, ParamConfig, EndpointIOType, ControllerVisitor } from '@travetto/rest';
+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 { AllViewSymbol } from '@travetto/schema/src/internal/types';
 
-import { ApiSpecConfig } from './config';
+import { ApiSpecConfig } from './config.ts';
 
 const DEFINITION = '#/components/schemas';
 
@@ -42,17 +41,6 @@ export class OpenapiVisitor implements ControllerVisitor<GeneratedSpec> {
     this.#config = config;
   }
 
-  /**
-   * Build response object
-   */
-  #getHeaderValue(ep: EndpointConfig, header: string): string | undefined {
-    let cType = ep.headers?.[header];
-    if (cType && typeof cType !== 'string') {
-      cType = cType();
-    }
-    return cType;
-  }
-
   /**
    * Convert schema to a set of dotted parameters
    */
@@ -206,7 +194,7 @@ export class OpenapiVisitor implements ControllerVisitor<GeneratedSpec> {
         };
 
         const properties: Record<string, SchemaObject> = {};
-        const def = config.views[AllViewSymbol];
+        const def = config.totalView;
         const required: string[] = [];
 
         for (const fieldName of def.fields) {
@@ -243,7 +231,7 @@ export class OpenapiVisitor implements ControllerVisitor<GeneratedSpec> {
   /**
    * Standard payload structure
    */
-  #getEndpointBody(body?: EndpointIOType, mime?: string): RequestBodyObject {
+  #getEndpointBody(body?: EndpointIOType, mime?: string | null): RequestBodyObject {
     if (!body) {
       return { content: {}, description: '' };
     } else if (body.type === Readable || body.type === Buffer) {
@@ -271,7 +259,7 @@ export class OpenapiVisitor implements ControllerVisitor<GeneratedSpec> {
   /**
    * Process endpoint parameter
    */
-  #processEndpointParam(ep: EndpointConfig, param: ParamConfig, field: FieldConfig): (
+  #processEndpointParam(ep: EndpointConfig, param: EndpointParamConfig, field: FieldConfig): (
     { requestBody: RequestBodyObject } |
     { parameters: ParameterObject[] } |
     undefined
@@ -279,12 +267,13 @@ export class OpenapiVisitor implements ControllerVisitor<GeneratedSpec> {
     const complex = field.type && SchemaRegistry.has(field.type);
     if (param.location) {
       if (param.location === 'body') {
+        const acceptsMime = ep.responseHeaderMap.get('accepts');
         return {
-          requestBody: field.specifiers?.includes('file') ? this.#buildUploadBody() : this.#getEndpointBody(field, this.#getHeaderValue(ep, 'accepts'))
+          requestBody: field.specifiers?.includes('file') ? this.#buildUploadBody() : this.#getEndpointBody(field, acceptsMime)
         };
       } else if (complex && (param.location === 'query' || param.location === 'header')) {
         return { parameters: this.#schemaToDotParams(param.location, field, param.prefix ? `${param.prefix}.` : '') };
-      } else if (param.location !== 'context') {
+      } else {
         const epParam: ParameterObject = {
           in: param.location,
           name: param.name || param.location,
@@ -293,8 +282,6 @@ export class OpenapiVisitor implements ControllerVisitor<GeneratedSpec> {
           schema: field.array ? { type: 'array', items: this.#getType(field) } : this.#getType(field)
         };
         return { parameters: [epParam] };
-      } else if (field.specifiers?.includes('file')) {
-        return { requestBody: this.#buildUploadBody() };
       }
     }
   }
@@ -303,7 +290,7 @@ export class OpenapiVisitor implements ControllerVisitor<GeneratedSpec> {
    * Process controller endpoint
    */
   onEndpointEnd(ep: EndpointConfig, ctrl: ControllerConfig): void {
-    if (this.#config.skipRoutes) {
+    if (this.#config.skipEndpoints || !ep.httpMethod) {
       return;
     }
 
@@ -314,43 +301,37 @@ export class OpenapiVisitor implements ControllerVisitor<GeneratedSpec> {
       responses: {},
       summary: ep.title,
       description: ep.description || ep.title,
-      operationId: `${ep.class.name}_${ep.handlerName}`,
+      operationId: `${ep.class.name}_${ep.name}`,
       parameters: []
     };
 
-    const pConf = this.#getEndpointBody(ep.responseType, this.#getHeaderValue(ep, 'content-type'));
+    const contentTypeMime = ep.responseHeaderMap.get('content-type');
+    const pConf = this.#getEndpointBody(ep.responseType, contentTypeMime);
     const code = Object.keys(pConf.content).length ? 200 : 201;
     op.responses![code] = pConf;
 
-    const schema = SchemaRegistry.getMethodSchema(ep.class, ep.handlerName);
+    const schema = SchemaRegistry.getMethodSchema(ep.class, ep.name);
     for (const field of schema) {
-      const res = this.#processEndpointParam(ep, ep.params[field.index!], field);
-      if (res) {
-        if ('parameters' in res) {
-          (op.parameters ??= []).push(...res.parameters);
+      const result = this.#processEndpointParam(ep, ep.params[field.index!], field);
+      if (result) {
+        if ('parameters' in result) {
+          (op.parameters ??= []).push(...result.parameters);
         } else {
-          op.requestBody ??= res.requestBody;
+          op.requestBody ??= result.requestBody;
         }
       }
     }
 
-    const epPath = (!ep.path ? '/' : ep.path).replace(/:([A-Za-z0-9_]+)\b/g, (__, param) => `{${param}}`);
-
-    const key = `${ctrl.basePath}${epPath}`.replace(/[\/]+/g, '/');
-
-    const toAdd = ep.method === 'all' ?
-      ['get', 'post', 'put', 'delete', 'patch'].reduce((acc, v) =>
-        ({ ...acc, [v]: { ...op, operationId: `${op.operationId}_${v}` } }), {}) :
-      { [ep.method]: op };
+    const key = ep.fullPath.replace(/:([A-Za-z0-9_]+)\b/g, (__, param) => `{${param}}`);
 
     this.#paths[key] = {
       ...(this.#paths[key] ?? {}),
-      ...toAdd
+      [HTTP_METHODS[ep.httpMethod].lower]: op
     };
   }
 
   onControllerEnd(controller: ControllerConfig): void {
-    if (this.#config.skipRoutes) {
+    if (this.#config.skipEndpoints) {
       return;
     }
     this.#tags.push({
@@ -365,19 +346,19 @@ export class OpenapiVisitor implements ControllerVisitor<GeneratedSpec> {
     }
 
     return {
-      tags: this.#tags.sort((a, b) => a.name.localeCompare(b.name)),
+      tags: this.#tags.toSorted((a, b) => a.name.localeCompare(b.name)),
       paths: Object.fromEntries(
         Object.entries(this.#paths)
-          .sort(([a], [b]) => a.localeCompare(b))
+          .toSorted(([a], [b]) => a.localeCompare(b))
           .map(([k, v]) => [k, Object.fromEntries(
             Object.entries(v)
-              .sort(([a], [b]) => a.localeCompare(b))
+              .toSorted(([a], [b]) => a.localeCompare(b))
           )])
       ),
       components: {
         schemas: Object.fromEntries(
           Object.entries(this.#schemas)
-            .sort(([a], [b]) => a.localeCompare(b))
+            .toSorted(([a], [b]) => a.localeCompare(b))
         )
       }
     };

package/support/bin/help.ts

@@ -22,7 +22,7 @@ export class OpenApiClientHelp {
         .map(x => x.replace(/^\s+-\s+/, '').trim());
 
       await fs.mkdir(path.dirname(formatCache), { recursive: true });
-      await fs.writeFile(formatCache, JSON.stringify([...lines.sort(),]));
+      await fs.writeFile(formatCache, JSON.stringify([...lines.toSorted(),]));
     }
     const list: string[] = JSON.parse(await fs.readFile(formatCache, 'utf8'));
     return list;

package/support/cli.openapi_client.ts

@@ -4,7 +4,7 @@ import cp from 'node:child_process';
 import { CliCommandShape, CliCommand, CliFlag } from '@travetto/cli';
 import { ExecUtil } from '@travetto/runtime';
 
-import { OpenApiClientHelp } from './bin/help';
+import { OpenApiClientHelp } from './bin/help.ts';
 
 /**
  * CLI for generating the cli client

package/support/cli.openapi_spec.ts

@@ -20,7 +20,7 @@ export class OpenApiSpecCommand implements CliCommandShape {
   }
 
   async main(): Promise<void> {
-    const { OpenApiService } = await import('../src/service');
+    const { OpenApiService } = await import('../src/service.ts');
 
     await RootRegistry.init();