diff --git a/.changeset/silver-ears-grin.md b/.changeset/silver-ears-grin.md index cf595da403..66eb0dfb37 100644 --- a/.changeset/silver-ears-grin.md +++ b/.changeset/silver-ears-grin.md @@ -2,4 +2,4 @@ '@backstage/repo-tools': minor --- -Adds support for auto generated server types from OpenAPI generator instead of dynamically implied types. This improves support for recursive types. +**BREAKING**: The `backstage-repo-tools package schema openapi generate --server` command now requires a client package to be accessible. This provides support for recursive types and completely aligns server and client types. [See the updated docs](https://backstage.io/docs/openapi/01-getting-started) for more information. diff --git a/docs/openapi/01-getting-started.md b/docs/openapi/01-getting-started.md index 156df9bd17..0c4f16d2ff 100644 --- a/docs/openapi/01-getting-started.md +++ b/docs/openapi/01-getting-started.md @@ -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 ` +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 ` 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 `. `` is a new directory and npm package that you should create. The general pattern is `plugins/-client` or if you want to co-locate this with your other shared types, use `plugins/-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 `. `` 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/-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, diff --git a/docs/openapi/generate-client.md b/docs/openapi/generate-client.md index b8acc331e5..1a31758502 100644 --- a/docs/openapi/generate-client.md +++ b/docs/openapi/generate-client.md @@ -20,9 +20,38 @@ info: ### Generating your client -1. Run `yarn backstage-repo-tools package schema openapi generate client --client-package `. This will create a new folder in `/src/generated` to house the generated content. -2. You should use the generated files as follows, +1. Run `yarn backstage-repo-tools package schema openapi generate --client-package `. This will create a new folder in `/src/generated` to house the generated content. We recommend that the client package be your plugin's common package. You should then add a new entry point into the package so that the generated content can be accessed like so, `-common/client`. To do that, adjust your `package.json` like so, -- `apis/DefaultApi.client.ts` - this is the client that you should use. It has types for all of the various operations on your API. -- `models/*` - These are the types generated from your OpenAPI file, ideally you should not need to use these directly and can instead use the inferred types from `apis/DefaultApi.client.ts`. -- everything else is directory specific and shouldn't be touched. +```json + // ... other scripts + + "exports": { + ".": "./src/index.ts", + "./alpha": "./src/alpha.ts", + // highlight-add-next-line + "./client": "./src/client.ts", + "./package.json": "./package.json" + }, + + "typesVersions": { + "*": { + "alpha": [ + "src/alpha.ts" + ], + // highlight-start + "client": [ + "src/client.ts" + ], + // highlight-end + "package.json": [ + "package.json" + ] + } + }, + + // ... other stuff +``` + +2. You should not need to import anything from subfolders of the `src/generated` parent folder, everything you should require will be accessible from the `src/generated/index.ts` file. Of note, +1. `DefaultApiClient` - this is the client that you can use to access your specific spec. +1. Any request or response types - these will be available from the index and should match the names in your spec.