Skip to content

Emit more correct openAPI spec - #2476

Open
four-random-common-words wants to merge 12 commits into
masterfrom
2024-emit-correct-api-spec
Open

Emit more correct openAPI spec#2476
four-random-common-words wants to merge 12 commits into
masterfrom
2024-emit-correct-api-spec

Conversation

@four-random-common-words

@four-random-common-words four-random-common-words commented Sep 7, 2026

Copy link
Copy Markdown

Issue: #2404
Frontend PR: hashtopolis/web-ui#817
Hashtopolis Client PR: hashtopolis/python-hashtopolis#11

Goal

Make the served OpenAPI spec describe what the helper endpoints actually return, and make the helper responses themselves JSON:API-compliant where they were not. This is the backend half of hashtopolis/web-ui#2404: the frontend generates its types from this spec, so every mismatch here became a runtime schema violation there.

How to review

Start with HelperApiPathBuilder.php and JsonApiFragments.php for the spec side, then AbstractBaseAPI.php and AbstractModelAPI.php for the permission split. The helper edits are small and follow from those. openapi.json and the fixtures are generated output; CI verifies they match the code, so skip them.

Mechanism

  1. Helpers declare their return shape precisely. getResponse() on a helper now distinguishes a single model ("File") from a list ("Task[]"). Two new optional hooks cover the cases a sample value cannot express: getMetaResponseSchema() for meta members with dynamic keys (dates, ids), and getNoContentMethods() for actions that answer 204.
  2. The spec builder emits a dedicated response component per helper. HelperApiPathBuilder turns those declarations into <Helper>Response schemas instead of pointing every helper at the model route's SingleResponse. To do so, ModelApiPathBuilder now registers each model's resource object as its own <Model>ResourceObject component so helpers can reference the same shape inside a slimmer envelope (jsonapi and data, no links or meta).
  3. Counts live in meta, resources live in data. Helpers that return plain numbers (completed counts, cracks per day) now put them under meta with an empty data array, as JSON:API requires. Helpers that return a model return it as a resource object under data.
  4. Permission checks are decoupled from serialization. preCommon() is split into bootRequest() (user lookup, AccessControl, route parser) and authorize() (permission check). The serializers getOneResource() and getManyResources() now only call bootRequest(). The action that invokes them does the permission check with its own requirements. This lets a POST helper return a model resource without also needing the model route's create permission.

Mechanical changes that follow

  • List helpers marked as lists. getAccessGroups, getBestTasksAgent, getCracksOfTask, getGlobalConfig declare Model[]. getCracksOfTask carries a comment that Hash[] is a simplification for the binary-hashlist case.
  • Count helpers moved to meta. getCompletedCount returns via getMetaResponse() and documents its keys with a sample map. getCracksPerDay uses getMetaResponseSchema() and still emits {} for an empty result.
  • recountFileLines returns the File. It hands back the model instead of an attribute array, so the file comes back as a resource object under data.
  • currentUser PATCH documented as 204. The spec no longer claims a 200 body for it.
  • Callers of the serializers check permissions themselves. AbstractModelAPI::get() calls preCommon(). The relationship routes call bootRequest() plus authorize() on the related API class before serializing.
  • Tests follow the contract. Integration tests read counts from meta and check the recounted file under data. FullSpecTest and SpecBuilderHelperApiTest assert the new helper response components and the 204. Three new spec fixtures (config, crackerbinarytype, hashtype) capture the added ResourceObject components.
  • openapi.json regenerated. Bulk diff, produced by the builder from the changes above.

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