Repository navigation
docs: SDK code samples on every API reference page, checked as code - #104
Merged
Merged
Conversation
Every one of the 48 operations now shows a TypeScript and a Python sample next to the generated curl (x-codeSamples), the first step of the API reference at Stripe's standard. Each sample is a real file: typescript/examples/api-reference/<operationId>.ts and python/examples/api_reference/<operation_id>.py. - scripts/add-openapi-code-samples.ts puts them in the bundle, as a step of npm run openapi; an operation without both files fails the build. - tests/architecture/openapi-code-samples.test.ts: every operation has both, the bundle holds exactly the files' text, no orphan samples, and every TypeScript sample typechecks against the SDK (strict). - python/tests/test_api_reference_samples.py: mypy --strict on every Python sample; ruff and black cover them in the Python workflow. types-requests joins the dev dependencies for that. - The five /external-connectors routes have no SDK method yet; their samples call the route directly and say so. Also: ADR-0014 marked accepted (PR #103 merged, proposed answers); book chapters 6 and 10 say the external release was checked live (CLAIMS 2.50) and add G-84; book PDF and llms files regenerated. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Automations to automatically generate PRs for you. |
…rses The docs preview build reported "Updated deployment with errors" for two pages, published broken on the live site: - concepts/human-approval.mdx: a code block inside a <Step> had been squashed onto one line, so its fence never closed. Rewritten as a real block. Also: the code list of approvers is codeApprovalIssuers.ts, and the hosted deployment's only code key is revoked; the current approver key came through maker checker. - changelog.mdx: '<action>' in plain text read as a tag; now code. tests/architecture/docs-pages-parse.test.ts compiles every page of the site with @mdx-js/mdx (new dev dependency) and fails on any that does not parse; it reports exactly the two errors Mintlify did, and passes now. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…schema Mintlify shows only the custom samples once x-codeSamples is set, so every operation now also has an explicit cURL sample, first, as Stripe orders them: openapi/code-samples/curl/<operationId>.sh. tests/architecture/openapi-code-samples.test.ts now also checks that each cURL sample calls its own operation's method and path, is valid shell (bash -n), and sends a literal JSON body the operation's request schema accepts (ajv 8, JSON Schema 2020-12; a sample with a misspelled required field fails). Bodies made at run time (a signed step up, a file) say where they come from instead. URLs with a query string are quoted. ajv 8 joins the dev dependencies (the 6 already installed cannot read 2020-12 schemas). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This branch was successfully deployed
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.
What
First step of the API reference at Stripe's standard: every one of the 48 operations shows a TypeScript and a Python sample next to the generated curl (
x-codeSamples).Each sample is a real file, checked like code:
typescript/examples/api-reference/<operationId>.tstests/architecture/openapi-code-samples.test.ts: typechecks every sample against the SDK (strict); every operation has both samples; the bundle holds exactly the files' text; no orphan samplespython/examples/api_reference/<operation_id>.pypython/tests/test_api_reference_samples.py:mypy --stricton every sample; ruff and black in the Python workflowscripts/add-openapi-code-samples.tsputs them in the bundle as a step ofnpm run openapi; an operation without both files fails the build. Apart from the samples, the bundle is unchanged (compared after parsing).The five
/external-connectorsroutes have no SDK method yet, so their samples call the route directly and say so. Adding those methods to both SDKs is a follow up for the next SDK release.Also
types-requestsadded to the Python dev dependencies (mypy needs it for the samples that call routes directly).Full preflight passed in the pre commit hook.
🤖 Generated with Claude Code