Backstage 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 |
| --- | --- | --- | --- | --- |
Progressive disclosure and bundled resources
references/upstream/SKILL.md: detailed OpenAPI onboarding and compatibility procedure.
Quality gate
1---2name: backstage-onboard-to-openapi-server3description: 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<!-- Generated from harness/github-copilot/plugins/open-horizons-platform/skills/backstage-onboard-to-openapi-server/SKILL.md by harness/claude-code/scripts/convert_from_copilot.py. Edit the source, not this file. -->89# Backstage Onboard a Backstage plugin to the OpenAPI server1011Reverse-engineer the current router once, make the OpenAPI specification authoritative, and12preserve runtime behavior through generated server types and focused tests.1314## When to invoke1516- "Convert this Backstage Express router to createOpenApiRouter."17- "Generate an OpenAPI server stub for this backend plugin."18- "Add a typed client for this Backstage API."19- "Migrate router tests to the OpenAPI wrapper."2021## Procedure22231. Confirm Backstage core or compatible fork mode, target plugin, green baseline, and exact source24 commit.252. Read [the pinned upstream procedure](references/upstream/SKILL.md).263. Keep typed client generation, test-wrapper migration, and changesets opt-in unless already27 required by the task.284. Inventory every mounted route, parameter, body, response, error, auth check, permission check,29 and nested router.305. Review the inventory before writing the specification.316. Author `openapi.yaml` as the new source of truth and validate it with repository tooling.327. Generate the server stub and switch to `createOpenApiRouter` without dropping auth,33 permissions, middleware, or error behavior.348. Add or migrate tests for success, validation, auth, permission, and error responses.359. Run targeted tests and exact root `yarn tsc` for Backstage core.3610. Add optional client, test-wrapper, and changeset work only when in scope.3738## Output template3940```markdown41## OpenAPI onboarding result4243**Plugin:** <path>44**Optional work:** <client, test wrapper, changeset>4546| Route | Spec operation | Auth and permission | Test | Status |47| --- | --- | --- | --- | --- |48```4950## Progressive disclosure and bundled resources5152- `references/upstream/SKILL.md`: detailed OpenAPI onboarding and compatibility procedure.5354## Quality gate5556- [ ] A green baseline exists before migration.57- [ ] Every route and nested router is inventoried.58- [ ] OpenAPI covers parameters, bodies, responses, and errors.59- [ ] Auth, permissions, middleware, and runtime behavior are preserved.60- [ ] Generated artifacts and optional work match the approved scope.61- [ ] Targeted tests and exact root `yarn tsc` pass.
paulasilvatech