docs(openapi): refresh the info block (description, contact) (#362)#363
Merged
Conversation
The spec's `info.description` undersold the API as "Customer and time-entry records" — 16 entities ago. Expand to the full entity list and call out the actual feature surface that operators care about when evaluating the API (idempotency, Link-header pagination, Prometheus /metrics, CSV export with formula-injection mitigation). Add a `contact` field pointing to the GitHub security policy. The project's vulnerability-report channel (private advisory + email fallback) is documented in SECURITY.md but Swagger UI's info panel never surfaced it — operators reading the docs in a browser had to leave the spec page to find the policy. The OpenAPI `contact` slot fits the link cleanly (Swagger UI renders contact.name + contact.url under "Contact the developer"). Pin the new fields with assertions in tests/api/openapi.test.js so a future re-write can't silently drop the license/contact pair — both matter for SBOM tooling and downstream Apache-2.0 redistributors that read the spec to populate their own metadata. Co-Authored-By: Claude Opus 4.7 (1M context) <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
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.
Closes #362.
Summary
Expands
info.descriptionto mention the 16-entity surface + operator-relevant features. Addsinfo.contactlinking to the GitHub security policy. Pin license + contact with new assertions intests/api/openapi.test.js.Test plan
npm run lint && npm test— 796 passing (assertions added to existing test, same test count).Proudly Made in Nebraska. Go Big Red! 🌽 https://xkcd.com/2347/