backstage
@backstage/openapi-utils
Summary
This package is meant to provide a typed Express router for an OpenAPI spec. Based on the oatx
library and adapted to override Express values.
Getting Started
Configuration
-
Run
yarn --cwd <package-dir> backstage-cli package schema openapi generate
to translate yoursrc/schema/openapi.yaml
to a new Typescript file insrc/schema/openapi.generated.ts
. The command will try to execute both a lint and prettier step on the generated file, where applicable. -
In your plugin's
src/service/createRouter.ts
,
import { createOpenApiRouter } from '../schema/openapi.generated';// ...export function createRouter() { const router = createOpenApiRouter(); // add routes to router, it's just an express router. return router;}
- Add
@backstage/backend-openapi-utils
to yourpackage.json
'sdependencies
.
Why do I need to add this to dependencies
? If you check the src/schema/openapi.generated.ts
file, we're creating a router stub for you with the @backstage/backend-openapi-utils
package.
Customization
If the out of the box router
doesn't work, you can do the following,
import { createOpenApiRouter } from '../schema/openapi.generated';// ...export function createRouter() { // See https://github.com/cdimascio/express-openapi-validator/wiki/Documentation for available options. const router = createOpenApiRouter(validatorOptions); // add routes to router, it's just an express router. return router;}
If you need even more control -- say for example you wanted to update the spec at runtime -- you can do the following,
import { spec } from '../schema/openapi.generated';import { createValidatedOpenApiRouter } from '@backstage/backend-openapi-utils';// ...export function createRouter() { // Update the spec here. const newSpec = { ...spec, myproperty123: 123 };
// See https://github.com/cdimascio/express-openapi-validator/wiki/Documentation for available options. const router = createValidatedOpenApiRouter<typeof newSpec>( newSpec, validatorOptions, ); // add routes to router, it's just an express router. return router;}
FAQs
Why am I getting unknown
as the type for a response?
This can happen when you have a charset
defined in your response.content
section. Something like response.content['application/json; charset=utf-8:']
will cause this issue.
INTERNAL
Limitations
as const
makes all fieldsreadonly
To ensure a good DX of using a simple imported JSON spec, we want to remove any type issues betweenreadonly
arrays and mutable arrays. Typescript does not allow them to be compared, so converting all imports from theopenapi3-ts
library toreadonly
is important. This is achieved through theImmutableObject
type intypes/immutable.ts
.
...// We want an interface like this,Router() as ApiRouter<typeof spec>
// Not an interface like this,Router() as ApiRouter<DeepWriteable<typeof spec>>...
Future Work
Response Validation
This is a murky ground and something that will take a while to gain adoption. For now, keep responses in the spec and at the type level, but will need to work to drive adoption of response validation.
Common Error Format
With the new createRouter
method, we can start to control error response formats for input and coercion errors.