docs(openapi): document bigint response header

[shivanshgupta365]

Summary

• document the Formance-Bigint-As-String response header as a reusable OpenAPI parameter
• reference it from every v2/v3 operation whose response renderer supports bigint string serialization
• regenerate the combined OpenAPI specification and API reference

Validation

• parsed openapi/v2.yaml, openapi/v3.yaml, and openapi.yaml as YAML
• verified exactly 10 affected operations in v2 and 9 in v3 reference the reusable parameter
• bundled both versioned specifications with Redocly
• git diff --check

Closes #1320

[claude]

Claude Code Review

This pull request is from a fork — automated review is disabled. A repository maintainer can comment @claude review to run a one-time review.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 28b1d03d-583a-4f9c-bf5c-ca97c325b1b0

📥 Commits

Reviewing files that changed from the base of the PR and between 9392241 and ab52d71.

⛔ Files ignored due to path filters (27)

• docs/api/README.md is excluded by !docs/api/**
• openapi.yaml is excluded by !**/*.yaml, !openapi.yaml
• openapi/v2.yaml is excluded by !**/*.yaml
• openapi/v3.yaml is excluded by !**/*.yaml
• pkg/client/.speakeasy/gen.lock is excluded by !**/*.lock, !**/*.lock, !pkg/client/**
• pkg/client/.speakeasy/logs/naming.log is excluded by !**/*.log, !**/*.log, !pkg/client/**
• pkg/client/docs/models/operations/v2createtransactionrequest.md is excluded by !pkg/client/**
• pkg/client/docs/models/operations/v2getaccountrequest.md is excluded by !pkg/client/**
• pkg/client/docs/models/operations/v2getbalancesaggregatedrequest.md is excluded by !pkg/client/**
• pkg/client/docs/models/operations/v2gettransactionrequest.md is excluded by !pkg/client/**
• pkg/client/docs/models/operations/v2getvolumeswithbalancesrequest.md is excluded by !pkg/client/**
• pkg/client/docs/models/operations/v2listaccountsrequest.md is excluded by !pkg/client/**
• pkg/client/docs/models/operations/v2listlogsrequest.md is excluded by !pkg/client/**
• pkg/client/docs/models/operations/v2listtransactionsrequest.md is excluded by !pkg/client/**
• pkg/client/docs/models/operations/v2reverttransactionrequest.md is excluded by !pkg/client/**
• pkg/client/docs/models/operations/v2runqueryrequest.md is excluded by !pkg/client/**
• pkg/client/models/operations/v2createtransaction.go is excluded by !pkg/client/**
• pkg/client/models/operations/v2getaccount.go is excluded by !pkg/client/**
• pkg/client/models/operations/v2getbalancesaggregated.go is excluded by !pkg/client/**
• pkg/client/models/operations/v2gettransaction.go is excluded by !pkg/client/**
• pkg/client/models/operations/v2getvolumeswithbalances.go is excluded by !pkg/client/**
• pkg/client/models/operations/v2listaccounts.go is excluded by !pkg/client/**
• pkg/client/models/operations/v2listlogs.go is excluded by !pkg/client/**
• pkg/client/models/operations/v2listtransactions.go is excluded by !pkg/client/**
• pkg/client/models/operations/v2reverttransaction.go is excluded by !pkg/client/**
• pkg/client/models/operations/v2runquery.go is excluded by !pkg/client/**
• pkg/client/v2.go is excluded by !pkg/client/**

📒 Files selected for processing (1)

• internal/api/v2/views_test.go

---

Walkthrough

The change adds v2 API tests for HeaderBigIntAsString parsing and balance rendering. The tests verify accepted truthy values, falsey values, and numeric or string serialization.

Changes

BigInt serialization test coverage

Layer / File(s)	Summary
BigInt header parsing tests internal/api/v2/views_test.go	Adds table-driven tests for case-insensitive truthy values and falsey or empty header values.
Balance rendering tests internal/api/v2/views_test.go	Adds table-driven tests for numeric output by default and string output when HeaderBigIntAsString is enabled.

Estimated code review effort: 2 (Simple) | ~10 minutes

Suggested reviewers: aalloiteau

Poem

A rabbit checks each number twice,
In JSON fields both sharp and nice.
With headers set, big values string,
Without them, numbers proudly spring.
The tests now guard this tidy thing.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Linked Issues check	❓ Inconclusive	The required OpenAPI files are excluded by path filters, so the header definition and endpoint references cannot be verified from the reviewable summary.	Review the excluded files openapi/v2.yaml and openapi/v3.yaml to verify the reusable parameter and all required endpoint references.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly describes documenting the bigint response header, which matches the pull request objective.
Description check	✅ Passed	The description explains the OpenAPI documentation, affected operations, regeneration, and validation for the bigint response header.
Out of Scope Changes check	✅ Passed	The reviewable test additions validate bigint header serialization behavior and are related to the linked issue.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 golangci-lint (2.12.2)

level=error msg="[linters_context] typechecking error: pattern ./...: directory prefix . does not contain main module or its selected dependencies"

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[NumaryBot]

✅ Approve — automated review

The PR consistently adds a reusable bigint response header parameter across the OpenAPI documents and regenerated client code, aligning with the existing bigint-as-string render paths. No correctness issues were identified by any reviewer, and the prior automated review also found nothing to flag. The changes are clean and ready to merge.

No findings.

[flemzord]

Thank you for your contribution @shivanshgupta365

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 81.42%. Comparing base (9392241) to head (ab52d71).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1663      +/-   ##
==========================================
+ Coverage   81.25%   81.42%   +0.16%     
==========================================
  Files         206      206              
  Lines       11302    11298       -4     
==========================================
+ Hits         9184     9199      +15     
+ Misses       1560     1555       -5     
+ Partials      558      544      -14     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.