Skip to content

Use OpenAPI path templates instead of Koa params - #325

Merged
kaareal merged 1 commit into
masterfrom
fix/openapi-path-templates
Sep 24, 2026
Merged

kaareal merged 1 commit into
masterfrom
fix/openapi-path-templates

Conversation

@kaareal

@kaareal kaareal commented Sep 24, 2026

Copy link
Copy Markdown
Collaborator

What

  • services/api/src/utils/openapi.js: generated and recorded path keys now use OpenAPI templates (/1/shops/{id}) instead of Koa params (/1/shops/:id), via a new toOpenApiPath().
  • services/api/openapi.json: existing path keys renamed in place, so recorded examples and edited descriptions are kept.
  • services/web/src/docs/utils/index.js: getRoutePath maps :id to {id}, so the MDX <Route route="GET /1/shops/:id" /> tags work without changes.

Why

Swagger rejected the spec with "parameter is not defined within path template". 25 path params across the spec had this error.

Notes for reviewers

  • Swagger still reports items must be a schema or array of schemas on Shop.address.geometry.coordinates (prefixItems + items: false). This PR leaves it alone: it is a valid OpenAPI 3.1 / JSON Schema 2020-12 tuple, and the error comes from Swagger's validator.
  • Lint and tests were not run locally because dependencies weren't installed in the worktree.

Paths like /1/shops/:id failed Swagger validation (parameter is not
defined within path template). Generated and recorded paths now use
/1/shops/{id}; the docs portal maps its :id route strings to match.
@github-actions

Copy link
Copy Markdown

API Changes

Operations

  • Added DELETE /1/auth/passkey/{id}
  • Added POST /1/users/{id}/authenticate
  • Added GET /1/users/{id}
  • Added PATCH /1/users/{id}
  • Added DELETE /1/users/{id}
  • Added GET /1/products/{id}
  • Added PATCH /1/products/{id}
  • Added DELETE /1/products/{id}
  • Added GET /1/shops/{id}
  • Added PATCH /1/shops/{id}
  • Added DELETE /1/shops/{id}
  • Added GET /1/uploads/{id}
  • Added DELETE /1/uploads/{id}
  • Added GET /1/uploads/{id}/url
  • Added GET /1/uploads/{id}/raw
  • Added POST /1/invites/{id}/resend
  • Added DELETE /1/invites/{id}
  • Added GET /1/templates/{id}
  • Added PATCH /1/templates/{id}
  • Added DELETE /1/templates/{id}
  • Added GET /1/templates/{id}/params
  • Added GET /1/templates/{id}/preview
  • Added POST /1/templates/{id}/send
  • Added GET /1/organizations/{id}
  • Added PATCH /1/organizations/{id}
  • Added DELETE /1/organizations/{id}
  • Removed DELETE /1/auth/passkey/:id
  • Removed POST /1/users/:id/authenticate
  • Removed GET /1/users/:id
  • Removed PATCH /1/users/:id
  • Removed DELETE /1/users/:id
  • Removed GET /1/products/:id
  • Removed PATCH /1/products/:id
  • Removed DELETE /1/products/:id
  • Removed GET /1/shops/:id
  • Removed PATCH /1/shops/:id
  • Removed DELETE /1/shops/:id
  • Removed GET /1/uploads/:id
  • Removed DELETE /1/uploads/:id
  • Removed GET /1/uploads/:id/url
  • Removed GET /1/uploads/:id/raw
  • Removed POST /1/invites/:id/resend
  • Removed DELETE /1/invites/:id
  • Removed GET /1/templates/:id
  • Removed PATCH /1/templates/:id
  • Removed DELETE /1/templates/:id
  • Removed GET /1/templates/:id/params
  • Removed GET /1/templates/:id/preview
  • Removed POST /1/templates/:id/send
  • Removed GET /1/organizations/:id
  • Removed PATCH /1/organizations/:id
  • Removed DELETE /1/organizations/:id

@kaareal
kaareal merged commit e6e7da7 into master Sep 24, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant