docs: document per-endpoint filter, sort, and search fields#18
Merged
Conversation
Port the OpenAPI documentation changes from Redocly/redocly#25078 to the standalone cafe-api repo. - Generalize the shared Filter and Search parameter descriptions, pointing readers to each list endpoint for the specific fields it supports. - Add per-endpoint description overrides (and examples) documenting the filterable, sortable, and searchable fields for menu and orders. - Document that order-items filtering is required and orderId-only. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
![redocly[bot]](https://avatars.githubusercontent.com/in/348054?s=60&v=4){kind=small}
There was a problem hiding this comment.
cafe AI Review: 🟢 Completed
Reunite Agent has reviewed your changes and found 10 potential issue(s).
Note
Low Risk
This is a documentation-only change to the OpenAPI specifications, introducing no operational or behavior changes to the application code.
Overview
Updates the OpenAPI specification to explicitly document per-endpoint filtering, sorting, and searching behaviors.
- Generalizes the shared
FilterandSearchparameter descriptions, directing users to individual endpoints for field specifics. - Adds endpoint-specific parameter description overrides in
paths/menu.yamlandpaths/orders.yamlto list supported sortable, filterable, and searchable fields along with examples. - Updates
paths/order-items.yamlto clarify that itsFilterparameter is required and restricted to theorderIdfield only.
DmitryAnansky
approved these changes
Jul 16, 2026
Address AI review feedback on #18: - Add maxLength to the shared filter (512) and search (256) query parameters to bound query-string size. - Add example values to the menu sort and search parameters for consistency with the orders endpoint. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
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
2 participants
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.
What / Why
Ports the OpenAPI documentation changes from Redocly/redocly#25078 to this standalone
cafe-apirepo. Only the spec/docs portion of that PR applies here — the app-code changes (Prisma DMMF removal, config-driven pagination engine) live in the monorepo and have no counterpart in this docs-only mirror.The upstream PR made cafe list pagination config-driven with an explicit per-endpoint field allow-list. This documents that behavior so the published spec matches what the API actually accepts.
Changes
components/parameters/Filter.yaml— generalized the shared description (points to each list endpoint for supported fields), scoped time ranges to date fields, and removed the orders-specific examples block (examples now live per-endpoint).components/parameters/Search.yaml— replaced the hard-coded per-endpoint field lists with a generic description pointing to each list endpoint.paths/menu.yaml— added siblingdescriptionoverrides on Sort/Filter/Search plus a Filterexample, documenting menu's sortable/filterable/searchable fields.paths/orders.yaml— same pattern for orders' Filter/Sort/Search, with examples.paths/order-items.yaml— documented that Filter is required andorderId-only, with an example.Testing
redocly lint openapi/cafe.yaml— valid.redocly bundle— each override resolves to its own path (Filterable/Sortable/Searchable field lists present per endpoint; order-items'orderId-only note resolved).🤖 Generated with Claude Code