paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 32 Packages Projects Releases Wiki Activity

adjust docs

Browse Source 
Signed-off-by: Aramis Sennyey <159921952+aramissennyeydd@users.noreply.github.com>
Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com>
This commit is contained in:
Aramis Sennyey
2024-04-01 19:25:59 -04:00
committed by aramissennyeydd
parent 9cf8209799
commit 23e2366911
3 changed files with 40 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/openapi/01-getting-started.md
+5 -5
View File
@@ -35,10 +35,10 @@ There are two required npm packages before we start,
1. `@backstage/repo-tools`, this package contains all OpenAPI-related commands for your plugins. We will be using this throughout the tutorial.
2. `@useoptic/optic`, this package is a dependency of `@backstage/repo-tools` but is only required for OpenAPI-related commands.
Further, for generating the client a `java` binary has to be available on your PATH.
You should install both of the above packages in the _root_ of your workspace.
Further, a `java` binary has to be available on your PATH.
## Storing your OpenAPI specification
You should create a new folder, `src/schema` in your backend plugin to store your OpenAPI (and any other) specifications. For example, if you're adding a specification to the catalog plugin, you would add a `src/schema` folder to `plugins/catalog-backend`, making a `plugins/catalog-backend/src/schema` directory. This directory should have an `openapi.yaml` file inside.
@@ -47,12 +47,12 @@ You should create a new folder, `src/schema` in your backend plugin to store you
## Generating a typed express router from a spec
Run `yarn backstage-repo-tools package schema openapi generate --server` from the directory with your plugin. This will create an `openapi.generated.ts` file in the `src/schema` directory that contains the OpenAPI schema as well as a generated express router with types. You should add this command to your `package.json` for future use, and you can combine both the server generation and the client generation below, like so, `yarn backstage-repo-tools package schema openapi generate --server --client-package <clientPackageDirectory>`
Run `yarn backstage-repo-tools package schema openapi generate --server` from the directory with your plugin. This will create a `router.ts` file in the `src/generated` directory that contains the OpenAPI schema as well as a generated express router with types. You should add this command to your `package.json` for future use and you can combine both the server generation and the client generation below like so, `yarn backstage-repo-tools package schema openapi generate --server --client-package <clientPackageDirectory>`
Use it like so, update your `router.ts` or `createRouter.ts` file with the following content,
```diff
+ import { createOpenApiRouter } from '../schema/openapi.generated';
+ import { createOpenApiRouter } from '../generated';
- import Router from 'express-promise-router';
...
@@ -65,7 +65,7 @@ export async function createRouter(
## Generating a typed client from a spec
From your current backend plugin directory, run `yarn backstage-repo-tools package schema openapi generate --client-package <plugin-client-directory>`. `<plugin-client-directory>` is a new directory and npm package that you should create. The general pattern is `plugins/<plugin-name>-client` or if you want to co-locate this with your other shared types, use `plugins/<plugin-name>-common`. You should add this command to your `package.json` for future use.
From your current backend plugin directory, run `yarn backstage-repo-tools package schema openapi generate --client-package <plugin-client-directory>`. `<plugin-client-directory>` is a new directory and npm package that you should create. The general pattern is to add a new entry point to your plugin's common package, `plugins/<plugin-name>-common/client`. You should add this command to your `package.json` for future use.
The generated client will have a directory `src/generated` that exports a `DefaultApiClient` class and all generated types. You can use the client like so,