adjust docs

Signed-off-by: Aramis Sennyey <159921952+aramissennyeydd@users.noreply.github.com>
Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com>

.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.

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 <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,
 

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 <directory>`. This will create a new folder in `<directory>/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 <directory>`. This will create a new folder in `<directory>/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, `<plugin>-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.