From 428af97ff58ca734f8735ac3aabfed5e714412e2 Mon Sep 17 00:00:00 2001 From: Chuck B Date: Wed, 15 Jan 2025 10:16:26 -0500 Subject: [PATCH 1/3] Update OpenAPI docs --- docs/python/reference/decorators.md | 2 +- .../reference/tools/time-travel-debugger.md | 2 +- .../tutorials/development/openapi-tutorial.md | 20 +++++++++---------- 3 files changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/python/reference/decorators.md b/docs/python/reference/decorators.md index 185abf0b5..14ea629b4 100644 --- a/docs/python/reference/decorators.md +++ b/docs/python/reference/decorators.md @@ -158,7 +158,7 @@ DBOS.kafka_consumer( ``` Runs a function for each Kafka message received on the specified topic(s). -Uses the Kafka message's topic, partition and offset to create a unique [workflow id](http://localhost:3000/python/reference/contexts#setworkflowid) to ensure once and only once execution. +Uses the Kafka message's topic, partition and offset to create a unique [workflow id](../reference/contexts#setworkflowid) to ensure once and only once execution. Takes a configuration dictionary and a list of topics to consume. The decorated function must take a KafkaMessage as its only parameter. diff --git a/docs/typescript/reference/tools/time-travel-debugger.md b/docs/typescript/reference/tools/time-travel-debugger.md index c26d78f7f..155361a06 100644 --- a/docs/typescript/reference/tools/time-travel-debugger.md +++ b/docs/typescript/reference/tools/time-travel-debugger.md @@ -158,7 +158,7 @@ The Debug Proxy listens on port 2345 by default. This port can be changed via th ### dbos-ttdbg.debug_pre_launch_task -By default, the [Time Travel Debugging CodeLens](http://localhost:3000/cloud-tutorials/timetravel-debugging#launching-a-debug-session) will use +By default, the [Time Travel Debugging CodeLens](../../../cloud-tutorials/timetravel-debugging#launching-a-debug-session) will use the settings from the first [VS Code launch configuration](https://code.visualstudio.com/docs/editor/debugging#_launch-configurations) that includes `dbos-cloud debug` in the command string. If there are no such launch configurations, the extension will create a launch configuration from scratch. The `dbos-ttdbg.debug_pre_launch_task` configuration setting is used as the diff --git a/docs/typescript/tutorials/development/openapi-tutorial.md b/docs/typescript/tutorials/development/openapi-tutorial.md index cd36ec790..68f10650e 100644 --- a/docs/typescript/tutorials/development/openapi-tutorial.md +++ b/docs/typescript/tutorials/development/openapi-tutorial.md @@ -20,10 +20,10 @@ To generate a OpenAPI definition file for a DBOS application, run the following npx dbos-openapi generate src/operations.ts ``` -This command takes a single required argument - the path to the DBOS application's TypeScript entrypoint files. +This command takes a single required argument - the path to the DBOS application's TypeScript entrypoint files. Lists of files and folders are also supported. For DBOS applications generated by [`npx @dbos-inc/create`](../../reference/tools/cli.md#npx-dbos-inccreate), the entrypoint will be `src/operations.ts`. -The `dbos-openapi generate` command generates an OpenAPI definition file `openapi.yaml` in the same folder as the entrypoint files. +The `dbos-openapi generate` command generates an OpenAPI definition file `.yaml` in the same folder as the entrypoint files. If multiple entrypoints are specified, multiple files will be created. ::::info This `entrypoints` argument is slightly different from the [`runtimeConfig.entrypoints`](../../reference/configuration.md#runtime) config setting. @@ -96,7 +96,7 @@ The server `basePath` must be included programmatically as in the code snippet a ### Specify OpenAPI Security Scheme and Requirements -DBOS [handlers](http://localhost:3000/tutorials/http-serving-tutorial#handlers) (i.e. methods with `@GetApi` or `@PostApi`) +DBOS [handlers](../requestsandevents/http-serving-tutorial#handlers) (i.e. methods with `@DBOS.getApi` or `@DBOS.postApi`) are mapped to OpenAPI [path items](https://spec.openapis.org/oas/v3.0.3#path-item-object). Path item operations optionally include security requirements, which map to security schemes defined in the `components.securitySchemes` section of the OpenAPI definition file. @@ -110,9 +110,9 @@ To include authentication information in the OpenAPI file, declare the security @Authentication(authMiddleware) @OpenApiSecurityScheme({ type: 'http', scheme: 'bearer' }) export class Operations { - @GetApi("/post/:id") - @RequiredRoles(['user']) - static async getPost(ctx: TransactionContext, @ArgSource(ArgSources.URL) id: string) { + @DBOS.getApi("/post/:id") + @DBOS.requiredRoles(['user']) + static async getPost(@ArgSource(ArgSources.URL) id: string) { ... } } @@ -126,18 +126,18 @@ The `@OpenApiSecurityScheme` decorator takes a single parameter, matching a supp :::: All handler methods on a class use the same `@OpenApiSecurityScheme` in the generated OpenAPI definition, -except for methods that have no specified [`@RequiredRoles`](../authentication-authorization#authorization-decorators). +except for methods that have no specified [`@DBOS.requiredRoles`](../authentication-authorization#authorization-decorators). DBOS does not check authentication or authorization info for methods without any required roles. Methods without any required roles do not emit security requirements in the generated OpenAPI definition file. ```typescript @Authentication(authMiddleware) -@DefaultRequiredRoles(['user']) +@DBOS.defaultRequiredRoles(['user']) @OpenApiSecurityScheme({ type: 'http', scheme: 'bearer' }) export class Operations { - @PostApi('/api/login') - @RequiredRoles([]) + @DBOS.postApi('/api/login') + @DBOS.requiredRoles([]) static async login(ctx: HandlerContext, username: string, password: string) { ... } From 4e97498f258b384e07ec16cb0f2f7d73914d4185 Mon Sep 17 00:00:00 2001 From: Chuck B Date: Wed, 15 Jan 2025 10:20:33 -0500 Subject: [PATCH 2/3] A protip --- docs/typescript/tutorials/development/openapi-tutorial.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/typescript/tutorials/development/openapi-tutorial.md b/docs/typescript/tutorials/development/openapi-tutorial.md index 68f10650e..0a25e274d 100644 --- a/docs/typescript/tutorials/development/openapi-tutorial.md +++ b/docs/typescript/tutorials/development/openapi-tutorial.md @@ -20,6 +20,10 @@ To generate a OpenAPI definition file for a DBOS application, run the following npx dbos-openapi generate src/operations.ts ``` +::::info +It is best to check that your code compiles before running `dbos-openapi generate`. +:::: + This command takes a single required argument - the path to the DBOS application's TypeScript entrypoint files. Lists of files and folders are also supported. For DBOS applications generated by [`npx @dbos-inc/create`](../../reference/tools/cli.md#npx-dbos-inccreate), the entrypoint will be `src/operations.ts`. From ffd79d858d52c41621a8cf2a2a491a25c5d91edb Mon Sep 17 00:00:00 2001 From: Chuck B Date: Wed, 15 Jan 2025 16:59:09 -0500 Subject: [PATCH 3/3] Restore some (not all) parts, w/ touchups --- docs/typescript/reference/configuration.md | 2 +- docs/typescript/reference/tools/cli.md | 11 ++++++++ .../reference/transactapi/dbos-class.md | 1 + .../transactapi/oldapi/decorators.md | 25 +++++++++++++++++++ 4 files changed, 38 insertions(+), 1 deletion(-) diff --git a/docs/typescript/reference/configuration.md b/docs/typescript/reference/configuration.md index 0283283af..bbbb6efde 100644 --- a/docs/typescript/reference/configuration.md +++ b/docs/typescript/reference/configuration.md @@ -74,7 +74,7 @@ If either does not exist, the Postgres role must have the [`CREATEDB`](https://w This section is used to specify DBOS runtime parameters. - **start**: The command to run to start your application. For example, if your main function is compiled to `dist/main.js`, your start command would be `node dist/main.js`. Mutually exclusive with entrypoints. -- **entrypoints** (optional): The compiled JavaScript files where DBOS looks for your application's code. Mutually exclusive with a start command, should only be used if you are using the DBOS HTTP decorators. At startup, the DBOS runtime automatically loads all classes exported from these files, serving their endpoints and registering their decorated functions. Defaults to `[dist/operations.js]`. +- **entrypoints** (optional): The compiled JavaScript files where DBOS looks for your application's code. This should only be used if you are using [scheduled workflows](./transactapi/dbos-class.md#scheduled-workflows), [Kafka consumers](../tutorials/requestsandevents/kafka-integration.md), or DBOS HTTP decorators in files that are not referenced by your `start` command. At startup, the DBOS runtime automatically loads all classes exported from these files, serving their endpoints and registering their decorated functions. Defaults to `[dist/operations.js]`. - **port** (optional): The port from which to serve your functions. Defaults to `3000`. Using [`npx dbos start -p `](./tools/cli#npx-dbos-start) overrides this config parameter. Only used if you are using the DBOS HTTP decorators. - **setup**: Setup commands to run before your application is built in DBOS Cloud. Used only in DBOS Cloud. Documentation [here](../../cloud-tutorials/application-management.md#customizing-microvm-setup) diff --git a/docs/typescript/reference/tools/cli.md b/docs/typescript/reference/tools/cli.md index 5aac29972..4f86ae94c 100644 --- a/docs/typescript/reference/tools/cli.md +++ b/docs/typescript/reference/tools/cli.md @@ -78,6 +78,17 @@ You must compile your code (`npm run build`) and start the debug proxy before ru - `-l, --loglevel `: The severity of log entries emitted. Can be one of `debug`, `info`, `warn`, `error`, `emerg`, `crit`, `alert`. - `-d, --appDir `: The path to your application root directory. +--- + +### `npx dbos-openapi generate` +**Description:** +This command generates an [OpenAPI 3.0.x](https://www.openapis.org/) definition file for a DBOS application. +For more information, please see the [OpenAPI Tutorial](../../tutorials/development/openapi-tutorial.md). +**Arguments:** +- ``: Path to the application's TypeScript entrypoint files or folders (for example, `src/a.ts src/operations/`) + +For a single entrypoint, the generated file is named `openapi.yaml` and is saved to the same directory as the TypeScript entrypoint file. If multiple files are specified, multiple `.yaml` files are generated. + ## Workflow Management Commands ### `npx dbos workflow list` diff --git a/docs/typescript/reference/transactapi/dbos-class.md b/docs/typescript/reference/transactapi/dbos-class.md index a1a21db80..efa5e6bcb 100644 --- a/docs/typescript/reference/transactapi/dbos-class.md +++ b/docs/typescript/reference/transactapi/dbos-class.md @@ -569,6 +569,7 @@ This provides the following features over using Koa directly: * Automatic configuration from `dbos-config.yaml` or the runtime environment * Automatic network configuration in DBOS Cloud * Default tracing, parsing, and other middleware, with [additional options](../../tutorials/requestsandevents/http-serving-tutorial.md#body-parser) +* Automatic generation of [OpenAPI](../../tutorials/development/openapi-tutorial.md) clients The following sections describe the decorators that can be used to register methods for HTTP serving. Note that all decorated methods must be `static`, as there is no mechanism to forward function calls to a specific object instance. diff --git a/docs/typescript/reference/transactapi/oldapi/decorators.md b/docs/typescript/reference/transactapi/oldapi/decorators.md index 37a32a40a..409fe2205 100644 --- a/docs/typescript/reference/transactapi/oldapi/decorators.md +++ b/docs/typescript/reference/transactapi/oldapi/decorators.md @@ -815,6 +815,31 @@ For a scheduled workflow to run at a given time, the time must match the crontab A time matches the pattern if all fields of the time match the pattern. Each field matches the pattern if its numerical value is within any of the inclusive ranges provided in the field, and is also divisible by the divisor. +### OpenAPI Decorators + +DBOS [can generate](../../../tutorials/development/openapi-tutorial.md) an [OpenAPI 3.0.3](https://spec.openapis.org/oas/v3.0.3) interface description for an application. While most information needed to generate the API is picked up from decorators such as [`@GetApi`](#getapi) or [`@ArgSource`](#argsource), some decorators provide specific details only needed by OpenAPI. + +#### `@OpenApiSecurityScheme` +This decorator is used to declare an [OpenAPI security scheme](https://spec.openapis.org/oas/v3.0.3#security-scheme-object) for the handler functions in a class. +This decorator takes a single parameter defining the security scheme as per the OpenAPI specification. +This decorator is purely declarative for the purpose of inclusion in the generated interface description. +You still need to implement authentication as per the [Authentication and Authorization tutorial](../../../tutorials/authentication-authorization). + +::::info +DBOS does not support the `oauth2` OpenAPI security scheme at this time. +:::: + +```typescript +@OpenApiSecurityScheme({ type: 'http', scheme: 'bearer' }) +@Authentication(authMiddleware) +export class Operations { + @DBOS.getApi("/post/:id") + static async getPost(id: string) { + ... + } +} +``` + ### Other Decorators #### TypeORM Decorators