diff --git a/plugins/openapi-router-common/README.md b/plugins/openapi-router-common/README.md deleted file mode 100644 index cda5d7fc7f..0000000000 --- a/plugins/openapi-router-common/README.md +++ /dev/null @@ -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_ diff --git a/plugins/openapi-router-common/.eslintrc.js b/plugins/openapi-router/.eslintrc.js similarity index 100% rename from plugins/openapi-router-common/.eslintrc.js rename to plugins/openapi-router/.eslintrc.js diff --git a/plugins/openapi-router/README.md b/plugins/openapi-router/README.md new file mode 100644 index 0000000000..ad45dae773 --- /dev/null +++ b/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 +} +``` + +### 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 +... +``` + +we need to type all internals of this package as `Immutable`. + +## 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. diff --git a/plugins/openapi-router-common/api-report.md b/plugins/openapi-router/api-report.md similarity index 100% rename from plugins/openapi-router-common/api-report.md rename to plugins/openapi-router/api-report.md diff --git a/plugins/openapi-router-common/package.json b/plugins/openapi-router/package.json similarity index 100% rename from plugins/openapi-router-common/package.json rename to plugins/openapi-router/package.json diff --git a/plugins/openapi-router-common/src/example.ts b/plugins/openapi-router/src/example.ts similarity index 100% rename from plugins/openapi-router-common/src/example.ts rename to plugins/openapi-router/src/example.ts diff --git a/plugins/openapi-router-common/src/index.ts b/plugins/openapi-router/src/index.ts similarity index 100% rename from plugins/openapi-router-common/src/index.ts rename to plugins/openapi-router/src/index.ts diff --git a/plugins/openapi-router-common/src/router.ts b/plugins/openapi-router/src/router.ts similarity index 87% rename from plugins/openapi-router-common/src/router.ts rename to plugins/openapi-router/src/router.ts index 3d46f7ce6f..15f4fe9b7a 100644 --- a/plugins/openapi-router-common/src/router.ts +++ b/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 = { - readonly [P in keyof T]: DeepReadonly; -}; - /** * Typed Express router based on an OpenAPI 3.1 spec. * @public diff --git a/plugins/openapi-router-common/src/run.ts b/plugins/openapi-router/src/run.ts similarity index 100% rename from plugins/openapi-router-common/src/run.ts rename to plugins/openapi-router/src/run.ts diff --git a/plugins/openapi-router-common/src/schema/petstore.ts b/plugins/openapi-router/src/schema/petstore.ts similarity index 100% rename from plugins/openapi-router-common/src/schema/petstore.ts rename to plugins/openapi-router/src/schema/petstore.ts diff --git a/plugins/openapi-router-common/src/setupTests.ts b/plugins/openapi-router/src/setupTests.ts similarity index 100% rename from plugins/openapi-router-common/src/setupTests.ts rename to plugins/openapi-router/src/setupTests.ts diff --git a/plugins/openapi-router-common/src/standaloneServer.ts b/plugins/openapi-router/src/standaloneServer.ts similarity index 100% rename from plugins/openapi-router-common/src/standaloneServer.ts rename to plugins/openapi-router/src/standaloneServer.ts diff --git a/plugins/openapi-router-common/src/types/common.ts b/plugins/openapi-router/src/types/common.ts similarity index 100% rename from plugins/openapi-router-common/src/types/common.ts rename to plugins/openapi-router/src/types/common.ts diff --git a/plugins/openapi-router-common/src/types/express.ts b/plugins/openapi-router/src/types/express.ts similarity index 100% rename from plugins/openapi-router-common/src/types/express.ts rename to plugins/openapi-router/src/types/express.ts diff --git a/plugins/openapi-router-common/src/types/immutable.ts b/plugins/openapi-router/src/types/immutable.ts similarity index 100% rename from plugins/openapi-router-common/src/types/immutable.ts rename to plugins/openapi-router/src/types/immutable.ts diff --git a/plugins/openapi-router-common/src/types/index.ts b/plugins/openapi-router/src/types/index.ts similarity index 100% rename from plugins/openapi-router-common/src/types/index.ts rename to plugins/openapi-router/src/types/index.ts diff --git a/plugins/openapi-router-common/src/types/requests.ts b/plugins/openapi-router/src/types/requests.ts similarity index 100% rename from plugins/openapi-router-common/src/types/requests.ts rename to plugins/openapi-router/src/types/requests.ts diff --git a/plugins/openapi-router-common/src/types/responses.ts b/plugins/openapi-router/src/types/responses.ts similarity index 100% rename from plugins/openapi-router-common/src/types/responses.ts rename to plugins/openapi-router/src/types/responses.ts diff --git a/yarn.lock b/yarn.lock index 91df44aac6..7601b411e7 100644 --- a/yarn.lock +++ b/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:^"