@travetto/openapi 8.0.0-alpha.2 → 8.0.0-alpha.20

package/README.md

@@ -117,40 +117,50 @@ export class ApiSpecConfig {
 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
-  -h, --help             display help for command
+  --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")
-  -h, --help                            display help for command
+  -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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@travetto/openapi",
-  "version": "8.0.0-alpha.2",
+  "version": "8.0.0-alpha.20",
   "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.2",
-    "@travetto/schema": "^8.0.0-alpha.2",
-    "@travetto/web": "^8.0.0-alpha.2",
-    "openapi3-ts": "^4.5.0",
-    "yaml": "^2.8.2"
+    "@travetto/config": "^8.0.0-alpha.19",
+    "@travetto/schema": "^8.0.0-alpha.19",
+    "@travetto/web": "^8.0.0-alpha.20",
+    "openapi3-ts": "^4.6.0",
+    "yaml": "^2.9.0"
   },
   "peerDependencies": {
-    "@travetto/cli": "^8.0.0-alpha.3"
+    "@travetto/cli": "^8.0.0-alpha.25"
   },
   "peerDependenciesMeta": {
     "@travetto/cli": {

package/support/bin/help.ts

@@ -12,7 +12,7 @@ export class OpenApiClientHelp {
 
   static async getListOfFormats(dockerImage: string): Promise<string[]> {
     const formatCache = Runtime.toolPath('openapi-formats.json');
-    if (!await fs.stat(formatCache).catch(() => 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]

package/support/cli.openapi_client.ts

@@ -7,21 +7,24 @@ 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[]> {

package/support/cli.openapi_spec.ts

@@ -7,7 +7,10 @@ import { Registry } from '@travetto/registry';
 import { DependencyRegistryIndex } from '@travetto/di';
 
 /**
- * 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 {