Build an API Documentation and Testing Workflow

The Problem

Your API documentation lives in a Notion page that was last updated four months ago. Three endpoints have been added since then, two have changed their request format, and one was deprecated. New developers waste half a day figuring out which docs are accurate. Partners integrating with your API open support tickets because the documented response format does not match what the API actually returns. Testing is manual -- someone runs curl commands from a shared script. The Stripe integration has never been tested with edge cases like disputed charges or failed subscription renewals because setting up those scenarios manually is tedious.

The Solution

Use the api-doc-generator to produce accurate OpenAPI documentation directly from the codebase, api-tester to systematically test every endpoint with automated assertions, and stripe-testing to validate payment flows with realistic scenarios including disputes, refunds, and webhook retries.

Step-by-Step Walkthrough

1. Generate API documentation from code

Extract route definitions, request/response types, and validation rules to produce documentation that cannot drift from the implementation.

Scan our Express API routes in src/routes/ and generate OpenAPI 3.1 documentation. Include request body schemas from our Zod validators, response types from our TypeScript return types, authentication requirements, and example values. Output both a JSON spec file and a hosted Swagger UI page.

The generator reads the actual Zod schemas used for validation, so the documented request format is exactly what the server accepts. No manual synchronization needed.

2. Test all endpoints systematically

Run every endpoint through happy path, error, and edge case scenarios.

Test all 34 endpoints in our API. For each endpoint, verify: correct HTTP status codes, response schema matches the OpenAPI spec, authentication is enforced on protected routes, validation rejects malformed input with helpful error messages, and pagination returns correct page sizes. Report failures as a summary table.

The test runner produces a table showing pass/fail status for every endpoint and test category:

API Test Results — 34 endpoints, 187 assertions
=================================================
Endpoint                    Status  Auth  Validation  Schema  Pagination
GET    /api/v1/products     PASS    PASS  PASS        PASS    PASS
POST   /api/v1/products     PASS    PASS  PASS        PASS    --
GET    /api/v1/products/:id PASS    PASS  PASS        PASS    --
PUT    /api/v1/products/:id PASS    PASS  PASS        PASS    --
DELETE /api/v1/products/:id PASS    PASS  PASS        PASS    --
GET    /api/v1/orders       PASS    PASS  PASS        PASS    PASS
POST   /api/v1/orders       PASS    PASS  FAIL *      PASS    --
GET    /api/v1/users        PASS    PASS  PASS        PASS    PASS
POST   /api/v1/checkout     PASS    PASS  PASS        FAIL *  --
...

Summary: 183 passed, 4 failed
  * POST /api/v1/orders     — empty body returns 500 instead of 400
  * POST /api/v1/checkout   — response missing "currency" field in schema
  * PUT  /api/v1/users/:id  — accepts invalid email format "not-an-email"
  * GET  /api/v1/reports     — returns 200 without auth header (should be 401)

The four failures represent real bugs. The orders endpoint crashes on empty bodies instead of returning a validation error, and the reports endpoint is missing authentication middleware entirely.

3. Validate Stripe payment flows end-to-end

Payment integrations have edge cases that only appear under specific conditions.

Test our Stripe integration with these scenarios: successful one-time payment, declined card (insufficient funds), 3D Secure authentication required, subscription creation with trial period, subscription upgrade with proration, failed renewal with automatic retry, disputed charge with evidence submission, and webhook replay for a missed event. Use Stripe test mode with appropriate test card numbers.

4. Set up continuous documentation and testing

Automate doc generation and API testing so they run on every pull request.

Create a CI workflow that regenerates the OpenAPI spec from code on every PR, diffs it against the previous version, and fails if endpoints changed without updating the changelog. Run the API test suite against a staging environment after every deployment.

Real-World Example

A payments platform had three partner companies struggling to integrate because the API docs showed v1 request formats while the live API had silently migrated to v2. The api-doc-generator produced accurate documentation in 20 minutes by reading the actual route definitions and Zod schemas. The api-tester discovered that 4 of 34 endpoints returned 500 errors on empty request bodies instead of 400 validation errors. The stripe-testing skill caught a critical bug: disputed charges were being processed as refunds, which meant the company was losing both the charge amount and the dispute fee. The total documentation and testing overhaul took two days and prevented an estimated $12,000 in monthly dispute losses.

Tips

• Generate documentation on every pull request and diff it against the previous version. If an endpoint's request schema changed but the changelog was not updated, fail the CI check.
• Test with realistic payloads, not minimal valid objects. An endpoint that accepts a product with a 3-character name might break when someone submits a 500-character name with Unicode characters.
• For Stripe testing, always test the webhook signature verification path. A common bug is accepting webhooks without verifying the signature, which allows attackers to forge events.
• Keep a separate test environment with its own Stripe test API keys. Sharing keys between developers causes test data collisions and flaky test results.