Update package name and add more details in the README.

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>

plugins/openapi-router-common/README.md

@@ -1,5 +0,0 @@
-# @backstage/plugin-openapi-router-common
-
-Welcome to the common package for the openapi-router plugin!
-
-_This plugin was created through the Backstage CLI_

plugins/openapi-router/README.md

@@ -0,0 +1,60 @@
+# @backstage/plugin-openapi-router
+
+## Purpose
+
+This package is meant to provide a typed Express router for an OpenAPI spec. Specs must be converted to JSON and then copied to a Typescript file.
+
+## Getting Started
+
+### Configuration
+
+In your plugin's `schema/openapi`,
+
+```ts
+export default {
+  // If your spec is in YAML, convert it to JSON, then paste it here.
+  // If your spec is in JSON, just paste it here.
+} as const;
+```
+
+In your plugin's `service/createRouter.ts`,
+
+```ts
+import {ApiRouter} from `@backstage/plugin-openapi-router`;
+import spec from './schema/openapi'
+...
+
+export function createRouter(){
+    const router = Router() as ApiRouter<typeof spec>
+}
+```
+
+### Limitations
+
+1. OpenAPI definitions must be converted to Typescript files
+   From [#32063](https://github.com/microsoft/TypeScript/issues/32063), we cannot import JSON `as const`. If we could, this would allow us to force all specs to be JSON and then just import from a spec.
+2. `as const` makes all fields `readonly`
+   To ensure a good DX of
+
+```tsx
+...
+Router() as ApiRouter<typeof spec>
+...
+```
+
+we need to type all internals of this package as `Immutable<T>`.
+
+## Future Work
+
+### Automatic generation of the `schema/openapi` file
+
+Ideally, this would be automatically generated on `openapi.yaml` updates (like a Webpack plugin), but could also be a CLI command.
+
+### Runtime validation
+
+Using a package like [`express-openapi-validator`](https://www.npmjs.com/package/express-openapi-validator), would allow us to remove [validation of request bodies with `AJV`](https://github.com/backstage/backstage/blob/master/plugins/catalog-backend/src/service/util.ts#L58).
+
+### PR-time verification.
+
+1. Verify that Typescript file matches the spec file.
+2. Verify that spec file matches the router input/output.

plugins/openapi-router/src/router.ts

@@ -16,14 +16,6 @@
 import { Router } from 'express';
 import { RequiredDoc, DocRequestMatcher } from './types';
 
-/**
- * Helper to transform readonly `as const` API specs for the ApiRouter.
- * @public
- */
-export type DeepReadonly<T> = {
-  readonly [P in keyof T]: DeepReadonly<T[P]>;
-};
-
 /**
  * Typed Express router based on an OpenAPI 3.1 spec.
  * @public

yarn.lock

@@ -7794,9 +7794,9 @@ __metadata:
   languageName: unknown
   linkType: soft
 
-"@backstage/plugin-openapi-router@workspace:^, @backstage/plugin-openapi-router@workspace:plugins/openapi-router-common":
+"@backstage/plugin-openapi-router@workspace:^, @backstage/plugin-openapi-router@workspace:plugins/openapi-router":
   version: 0.0.0-use.local
-  resolution: "@backstage/plugin-openapi-router@workspace:plugins/openapi-router-common"
+  resolution: "@backstage/plugin-openapi-router@workspace:plugins/openapi-router"
   dependencies:
     "@backstage/backend-common": "workspace:^"
     "@backstage/cli": "workspace:^"