Repository navigation
Conversation
The REST table was twenty-five hand-typed rows kept in step with the code by
memory. Render it from the spec between markers as part of openapi:gen, add
`npm run openapi:check` to CI so the build fails on drift, and assert the
committed README matches a fresh rendering in tests/openapi.test.ts.
Regenerating corrected the table: paths now use OpenAPI {param} syntax, the
example query strings the spec cannot encode are gone, the missing
POST /pairs row appears, and GET/POST /graphql are separate rows.
Co-Authored-By: Codebuff <noreply@codebuff.com>
Miracle656
left a comment
Miracle656
left a comment
There was a problem hiding this comment.
Generating the endpoint table from openapi.yaml is the right idea and I have been asking for it — a hand-maintained route table rots, and --check wired into CI is what stops it. Coverage goes from 29 documented endpoints to 39, which is the gain. Two things to fix first.
1. The path style breaks 16 existing tests
tests/rest-route.test.ts (already on main) parses the README table and asserts every documented route is registered in Fastify. Fastify registers :param; the generator emits OpenAPI's {param}:
main | GET | `/price/:assetA/:assetB` |
generated | GET | `/price/{assetA}/{assetB}` |
so every parameterised route stops matching — 16 failures, all of the form should have GET /price/{assetA}/{assetB} registered. I confirmed this is the PR rather than staleness: it fails before and after npm run openapi:gen.
One transform in the writer fixes it — convert {name} to :name when emitting the table. That keeps the README in the syntax the rest of the repo already uses and leaves the existing regression test working, which is worth more than matching OpenAPI's spelling in a human-facing table.
2. It drops 16 of the 17 curl examples
This is the part I would not merge without you deciding on it. On main, 17 of 29 rows carry a worked query string:
| GET | `/price/:assetA/:assetB/route?amount=1000` | Best execution route for a given amount |
| GET | `/impact/:assetA/:assetB?thresholds=1,5,10` | Adaptive slippage ladder and threshold crossing sizes |
| GET | `/price/:assetA/:assetB/history?window=1h` | OHLCV history |
After generation, 1 of 39 does. Those examples are the reason the table is useful — /impact/:a/:b without ?thresholds= does not tell a reader what the endpoint wants, and this section is what people copy into a terminal.
The spec already carries what you need: the parameters have example: values. Appending the examples for required query parameters (or a curated x-readme-example on the operation, if you would rather keep the choice editorial) gets both properties — can't rot, still useful.
Smaller
The --check failure message is good: naming the drifted artifact and printing the exact command to fix it is what someone staring at a red CI job needs. Worth noting that CI now has three generated-artifact guards — this one, openapi.json matching the generator, and #403's git diff --exit-code -- clients/typescript. That is not too many, but they should fail with the same shape of message, and yours is the best of the three.
Get those two sorted and I will take it quickly — this is a maintenance win and I would rather have it than not.
Resolve conflicts with Divinity-Labs#475, which landed scripts/generate-readme.ts and the <!-- ENDPOINTS:START --> generated README table on main: - README.md: keep main's single generated endpoint table (ENDPOINTS markers) instead of a second BEGIN/END GENERATED ENDPOINT TABLE block, regenerate it from main's openapi.yaml, and keep the note that the table is generated. - package.json: keep both sides' scripts (openapi:check, graphql:schema:gen, readme:gen, client:gen, client:typecheck). - scripts/generate-openapi.ts: openapi:gen / openapi:check now delegate the README rendering to generate-readme.ts so there is one renderer, while still regenerating/checking openapi.json and the README in one command. - tests/openapi.test.ts: drop the duplicated coverage/generator imports and assert openapi:check reports no stale artifacts (row-level README checks live in tests/readme.test.ts). - ci.yml: run openapi:check after prisma generate (the README renderer loads the venue registry).
|
Closing this one as superseded, not rejected — and the thing it was for is already live on #475 landed the same capability in b25e975: The The part that is still unbuilt, if you want it The second thing I raised last round never got implemented anywhere, including on Not one row in the generated table carries a query string. That is a real improvement against |
Summary
Documents the "/status" endpoint in the OpenAPI specification, making its response structure and health conditions clear for integrators and monitoring systems.
Changes
Closes #273.