Onboard a Backstage plugin to the OpenAPI server
Reverse-engineer the current router once, make the OpenAPI specification authoritative, and
preserve runtime behavior through generated server types and focused tests.
When to invoke
- "Convert this Backstage Express router to createOpenApiRouter."
- "Generate an OpenAPI server stub for this backend plugin."
- "Add a typed client for this Backstage API."
- "Migrate router tests to the OpenAPI wrapper."
Procedure
- Confirm Backstage core or compatible fork mode, target plugin, green baseline, and exact source
commit.
- Read the pinned upstream procedure.
- Keep typed client generation, test-wrapper migration, and changesets opt-in unless already
required by the task.
- Inventory every mounted route, parameter, body, response, error, auth check, permission check,
and nested router.
- Review the inventory before writing the specification.
- Author
openapi.yaml as the new source of truth and validate it with repository tooling.
- Generate the server stub and switch to
createOpenApiRouter without dropping auth,
permissions, middleware, or error behavior.
- Add or migrate tests for success, validation, auth, permission, and error responses.
- Run targeted tests and exact root
yarn tsc for Backstage core.
- Add optional client, test-wrapper, and changeset work only when in scope.
Output template
## OpenAPI onboarding result
**Plugin:** <path>
**Optional work:** <client, test wrapper, changeset>
| Route | Spec operation | Auth and permission | Test | Status |
| --- | --- | --- | --- | --- |
Quality gate
1---2name: onboard-to-openapi-server-23description: Migrate a Backstage backend plugin from a hand-written Express router to the repository's typed OpenAPI server tooling while preserving routes, auth, permissions, errors, tests, and optional client generation. Use when onboarding createOpenApiRouter or modernizing a router with OpenAPI.4license: Apache-2.05---67# Onboard a Backstage plugin to the OpenAPI server89Reverse-engineer the current router once, make the OpenAPI specification authoritative, and10preserve runtime behavior through generated server types and focused tests.1112## When to invoke1314- "Convert this Backstage Express router to createOpenApiRouter."15- "Generate an OpenAPI server stub for this backend plugin."16- "Add a typed client for this Backstage API."17- "Migrate router tests to the OpenAPI wrapper."1819## Procedure20211. Confirm Backstage core or compatible fork mode, target plugin, green baseline, and exact source22 commit.232. Read [the pinned upstream procedure](references/upstream/SKILL.md).243. Keep typed client generation, test-wrapper migration, and changesets opt-in unless already25 required by the task.264. Inventory every mounted route, parameter, body, response, error, auth check, permission check,27 and nested router.285. Review the inventory before writing the specification.296. Author `openapi.yaml` as the new source of truth and validate it with repository tooling.307. Generate the server stub and switch to `createOpenApiRouter` without dropping auth,31 permissions, middleware, or error behavior.328. Add or migrate tests for success, validation, auth, permission, and error responses.339. Run targeted tests and exact root `yarn tsc` for Backstage core.3410. Add optional client, test-wrapper, and changeset work only when in scope.3536## Output template3738```markdown39## OpenAPI onboarding result4041**Plugin:** <path>42**Optional work:** <client, test wrapper, changeset>4344| Route | Spec operation | Auth and permission | Test | Status |45| --- | --- | --- | --- | --- |46```4748## Quality gate4950- [ ] A green baseline exists before migration.51- [ ] Every route and nested router is inventoried.52- [ ] OpenAPI covers parameters, bodies, responses, and errors.53- [ ] Auth, permissions, middleware, and runtime behavior are preserved.54- [ ] Generated artifacts and optional work match the approved scope.55- [ ] Targeted tests and exact root `yarn tsc` pass.
paulasilvatech