To make things work, there's a new Caddyfile and .tool-versions dependency to serve /docs and app on the same port locally. See README for how to run it.
The new documentation examples use monaco editor and JSON schema under the hood for editing and validation
The new /api/docs/query endpoint is unique for docs and uses cookie-based auth, see companion PR linked above
json-stringify-pretty-compact is a new dependency used to make json output from API more readable.
Needed to eject Tabs component from docusaurus to make it controllable. This will need to be accounted for when updating dependencies in the future.
Open question:
I haven't tested this on mobile layouts: @ukutaht curious on your thoughts/priority on this. Examples probably don't need to be editable/runnable on mobile.
Design, content feedback is 100% welcome!
Next steps/not part of this PR:
Move schema file to main repo, use for validations. Copy or pull via endpoint into this repo
Introduce typescript, convert js files to typescript
Add test suite running/validating examples to main repo
Companion PR: https://github.com/plausible/analytics/pull/4453 (merge and deploy first)
This PR introduces APIv2 documentation with interactive examples.
Peek 2024-08-22 09-03.webm
Notes on the implementation:
Open question:
Next steps/not part of this PR: