Fix naming and API report.

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
2023-03-06 11:18:42 -05:00
parent c6c01b5e2e
commit 978b09f273
17 changed files with 9 additions and 6 deletions
@@ -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`,
+
+```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 using a simple imported JSON spec, we want to remove any type issues between `readonly` arrays and mutable arrays. Typescript does not allow them to be compared, so converting all imports from the `openapi3-ts` library to `readonly` is important.
+
+```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.