Skip to content

Commit

Permalink
Rename/repackage openapi command (#45)
Browse files Browse the repository at this point in the history
Openapi command now comes from a separate package, update doc
accordingly.
  • Loading branch information
chuck-dbos authored Jan 22, 2024
1 parent 68ec449 commit da89fdf
Show file tree
Hide file tree
Showing 2 changed files with 14 additions and 9 deletions.
2 changes: 1 addition & 1 deletion docs/api-reference/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ This command initializes a new DBOS application from a template into a target di
**Parameters:**
- `-n, --appName <application-name>`: The name and directory to which to initialize the application.

### `npx dbos-sdk openapi`
### `npx dbos-openapi generate`

**Description:**
This command generates an [OpenAPI 3.0.x](https://www.openapis.org/) definition file for a DBOS application.
Expand Down
21 changes: 13 additions & 8 deletions docs/tutorials/openapi-tutorial.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,25 +4,30 @@ title: OpenAPI Support
description: Learn how to automatically generate clients for DBOS applications.
---

[DBOS CLI](../api-reference/cli.md) v0.6 adds the `openapi` command that generates an [OpenAPI 3.0.x](https://www.openapis.org/) definition file for a DBOS application.
[DBOS CLI](../api-reference/cli.md) v0.6 adds the `dbos-openapi generate` command that generates an [OpenAPI 3.0.x](https://www.openapis.org/) definition file for a DBOS application.
This definition file can be used to automatically generate strongly typed client code to invoke DBOS application endpoints.

### Generate OpenAPI Definition File

To generate a OpenAPI definition file for a DBOS application, run the following `dbos-sdk` cli command:
First, install `@dbos-inc/dbos-openapi` as a development dependency in your project:
```shell
npm install --save-dev @dbos-inc/dbos-openapi
```

To generate a OpenAPI definition file for a DBOS application, run the following `dbos-openapi` cli command:

```shell
npx dbos-sdk openapi src/operations.ts
npx dbos-openapi generate src/operations.ts
```

This command takes a single required argument - the path to the DBOS application's TypeScript entrypoint file.
For DBOS applications generated by [`dbos-sdk init`](../api-reference/cli.md#npx-dbos-sdk-init), the entrypoint will be `src/operations.ts`.

The `dbos-sdk openapi` command generates an OpenAPI definition file `openapi.yaml` in the same folder as the entrypoint file.
The `dbos-openapi generate` command generates an OpenAPI definition file `openapi.yaml` in the same folder as the entrypoint file.

::::info
This entrypoint argument is slightly different from the [`runtimeConfig.entrypoint`](../api-reference/configuration.md#runtime) config setting.
The `dbos-sdk openapi` argument references the TypeScript entrypoint file.
The `dbos-openapi generate` argument references the TypeScript entrypoint file.
The `runtimeConfig.entrypoint` setting references the JavaScript file generated from the TypeScript entrypoint file.
::::

Expand All @@ -41,7 +46,7 @@ Some of these tools include:

We can't provide tutorials for all of these OpenAPI generator tools, but the Swagger Editor runs in the browser so is straightforward to use for a simple tutorial

First, you need to run `npx dbos-sdk openapi` against your DBOS application entrypoint as described above.
First, you need to run `npx dbos-openapi generate` against your DBOS application entrypoint as described above.

::::info
Note, the shop and payment backend applications from the [DBOS E-Commerce demo app](./demo-apps.md#e-commerce)
Expand All @@ -53,7 +58,7 @@ Swagger Editor will validate the OpenAPI definitions and render a documentation

::::info
Note, the Swagger Editor generated documentation includes tooling to trigger OpenAPI endpoints from directly in the web page.
This tooling will not work as the OpenAPI definition generated by `dbos-sdk openapi` does not include server URL information.
This tooling will not work as the OpenAPI definition generated by `dbos-openapi generate` does not include server URL information.
::::

At the top of the Swagger Editor, there is a "Generate Client" dropdown menu. Select typescript-axios from the menu.
Expand Down Expand Up @@ -117,7 +122,7 @@ The `@OpenApiSecurityScheme` decorator takes a single parameter, matching a supp
[from the OpenAPI spec](https://spec.openapis.org/oas/v3.0.3#security-scheme-object).

::::info
`dbos-sdk openapi` does not support the `oauth2` OpenAPI security scheme at this time.
`dbos-openapi generate` does not support the `oauth2` OpenAPI security scheme at this time.
::::

All handler methods on a class use the same `@OpenApiSecurityScheme` in the generated OpenAPI definition,
Expand Down

0 comments on commit da89fdf

Please sign in to comment.