Add OpenAPI 3.0 documentation#165
Draft
tvdeyen wants to merge 9 commits into
Draft
Conversation
tvdeyen
force-pushed
the
add-openapi-docs
branch
5 times, most recently
from
March 21, 2026 22:31
7fd57cf to
f5e4e87
Compare
Covers all public and admin endpoints (pages, layout_pages, nodes), all resource schemas (page, element, language, node), all 15 ingredient type schemas, pagination, filtering, sparse fieldsets, and caching headers.
Adds OpenapiController that loads the YAML spec once and serves it as JSON. Clients and tools like Swagger UI can discover the API at /jsonapi/openapi.json.
Add rspec-openapi to Gemfile and configure it in spec/support/openapi.rb to regenerate docs/openapi.yml from request specs when running with OPENAPI=1. The gem merges actual JSON:API responses into the existing spec file, preserving hand-written component schemas. Also includes docs/openapi.yml in the gemspec file list and documents the workflow in the README.
Runs the test suite with OPENAPI=1 and fails if docs/openapi.yml has uncommitted changes, ensuring the checked-in spec stays in sync with the actual API responses.
Expand the Contributing section with step-by-step instructions including the OpenAPI regeneration step. Add a note to the OpenAPI section about the CI drift check.
Useful for working with Bruno App
Necessary if you want to serve from the dummy app.
Serves a lightweight HTML page that loads Swagger UI from the CDN and points it at the existing /jsonapi/openapi.json endpoint. No extra gem dependencies required. Signed-off-by: Thomas von Deyen <thomas@vondeyen.com>
Update generated OpenAPI spec with tags, schemas, and component definitions. Signed-off-by: Thomas von Deyen <thomas@vondeyen.com>
tvdeyen
force-pushed
the
add-openapi-docs
branch
from
July 18, 2026 15:41
5410f0b to
0c5bdd2
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
A special treat for my friend @lassediercks ❤️
docs/openapi.yml) covering all public and admin endpoints (pages, layout pages, nodes), resource schemas, all 15 ingredient types, pagination, filtering, sparse fieldsets, and caching headersGET /openapi.jsonendpoint (OpenapiController) that serves the spec as JSON for tools like Swagger UI and RedocOPENAPI=1 bundle exec rspec)docs/openapi.ymlis out of dateHow it works
The OpenAPI spec is a hand-written YAML file with detailed component schemas. Running
OPENAPI=1 bundle exec rspecuses rspec-openapi to merge actual API response shapes into thepathssection while preserving hand-written schemas. CI enforces that the committed spec matches what the tests produce.