API Contract & OpenAPI Testing

This page documents the RitoSwap-specific contract test suite in:


app/api/__contract__/contract.test.ts

It is focused on the four public, token-gate–related endpoints actually used in this repo:

GET /api/nonce
POST /api/gate-access
GET /api/token-status/{tokenId}
POST /api/form-submission-gate

All tests validate against the project’s OpenAPI spec:


public/openapi.json

💡

These tests are not generic examples. They encode the exact response shapes, status codes, and error formats that RitoSwap promises at its token-gate surface area.

What these tests cover

The contract suite models RitoSwap’s public contract at the HTTP layer.

- - - contract.test.ts
- openapi.json

At a high level, contract.test.ts defines:

Types dedicated to this file:
- HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH'
- ContractTestCase with name, status, and response shape
- ContractTest grouping a path, method, and testCases[]
A CONTRACT_TESTS array with hand-authored examples for each RitoSwap endpoint.
A coerceMessageEnumIfPresent() helper tuned to the /api/form-submission-gate success schema.
A describe('API Contract Tests') block that:
- Hydrates OpenAPITestValidator via getOpenAPIValidator() from @/e2e/supertest/openapi-validator.
- Iterates the RitoSwap endpoints only and calls validator.validateResponse(...).
- Runs two meta-tests to track coverage across all paths and response codes in openapi.json.

No route handlers are imported. This file is purely about matching RitoSwap’s documented contract.

Endpoint matrix

Endpoint matrix (RitoSwap-specific)

The CONTRACT_TESTS array is hand-curated around the four token-gate endpoints.

1. `GET /api/nonce`

Used for SIWE nonce generation, with cases:

Status	Case name	Shape (project-specific)
`200`	Returns nonce successfully	`{ nonce: '0123456789abcdef0123456789abcdef' }` (32 hex chars)
`501`	SIWE not enabled	Problem JSON with `type`, `title: ‘SIWE not enabled’`, and RitoSwap’s error copy.
`429`	Rate limited	Problem JSON titled `‘Too many requests’` with RitoSwap’s nonce-specific detail string.
`405`	Method not allowed	Legacy simple shape: `{ error: 'Method not allowed' }`
`500`	Internal server error	Problem JSON with `‘Failed to generate nonce’` copy.

2. `POST /api/gate-access`

This is the core token-gate endpoint. The contract tests codify the shapes your docs promise:

Success (200 Access granted):
- success: true, access: 'granted'
- content.welcomeText and content.textSubmissionAreaHtml
- Fully populated content.audioData object with RitoSwap’s fields (headline, imageSrc, audioSrc, etc.).
Failures, all using RitoSwap’s problem+json format with stable titles:

Status	Title	Scenario
`400`	`Invalid request`	Body validation failed or required fields missing.
`401`	`Authentication failed`	SIWE/JWT/signature issues.
`403`	`You do not own this token`	On-chain ownership check fails.
`403`	`This token has already been used`	Token exists but is marked as consumed in DB.
`404`	`Token not found in database`	On-chain token exists but has no DB record yet.
`429`	`Too many requests`	Rate-limit envelope for this endpoint.
`500`	`Internal server error`	Generic “unexpected error” surface for gate access.

3. `GET /api/token-status/{tokenId}`

This endpoint reports whether a key token exists and whether it has been used for gating. The contract tests model:

Token exists and unused (200):
- {'{ exists: true, used: false, count: 1, usedBy: null, usedAt: null }'}
Token exists and used (200):
- Same fields, with used: true, a concrete usedBy address, and ISO timestamp usedAt.
Token does not exist (200):
- {'{ exists: false, used: false, count: 0, usedBy: null, usedAt: null }'}
Error envelopes:
- 400 Invalid token ID format (legacy, simple {'{ error: \'Invalid token ID format\' }'}).
- 405 Method not allowed with {'{ error: \'Method not allowed\' }'}.
- 429 Too many requests problem JSON.
- 500 Internal server error with a simplified {'{ error: \'Internal server error\' }'} body.

The distinction between “token not found” and “invalid token ID” is encoded explicitly here, not just implied by implementation.

4. `POST /api/form-submission-gate`

This endpoint stores gated form submissions tied to a token. Contract tests cover:

Success (200 Submission successful):
- {'{ success: true, message: \'Form submission saved successfully!\' }'}
- At runtime, coerceMessageEnumIfPresent() can tweak message to align with the OpenAPI enum if wording drifts.
Failure shapes, all project-specific:

Status	Body	Meaning
`401`	`{ success: false, error: 'Invalid signature' }`	Signature mismatch or auth failure.
`403`	`{ success: false, error: 'Token not found or already used' }`	Token not present or already consumed.
`500`	`{ success: false, error: 'Failed to save message' }`	Persistence failure.
`400`	`{ success: false, error: 'Invalid request body' }`	Schema or required field issues.
`405`	`{ error: 'Method not allowed' }`	Non-POST usage.
`429`	Problem JSON titled `‘Too many requests’`	Rate limiting for form submissions.

How the validator is wired

How the validator is wired (in this repo)

The contract suite is wired tightly to your existing supertest-based OpenAPI validator.

1. Import the validator type

The test imports OpenAPITestValidator from:


import type { OpenAPITestValidator } from '@/e2e/supertest/openapi-validator'

and hydrates it in beforeAll using getOpenAPIValidator() from the same module.

2. Hydrate the spec from `public/openapi.json`

Instead of hard-coding schemas, the test reads the exact file that your Swagger UI uses:


const openApiSpec = JSON.parse(
  fs.readFileSync(path.join(process.cwd(), 'public/openapi.json'), 'utf-8')
)

3. Build mock responses shaped like supertest output

For each ContractTestCase, the suite builds:


const mockResponse = {
  status,
  body,
  headers: {
    'content-type': 'application/json; charset=utf-8',
    'x-powered-by': 'Next.js',
  },
}

This mirrors how supertest would present a response object to the validator.

4. Validate per path + method

The validator is called with RitoSwap’s concrete path and method:


const validation = validator.validateResponse(
  mockResponse as any,
  suitePath,
  method,
)

Failures log the method, path, case name, response body, and errors for debugging.

5. Handle message enums on `/api/form-submission-gate`

The helper coerceMessageEnumIfPresent() inspects the OpenAPI schema for that endpoint and status. If it finds a properties.message.enum, it coerces the test body’s message into an allowed value when needed.

This keeps the test robust even if you slightly tweak human-facing copy but keep the enum list.

Keeping spec + tests in sync

Keeping spec + tests in sync (RitoSwap workflow)

In this project, contract tests are part of your gated API workflow, not a generic tutorial.

When to touch `contract.test.ts`

Update this file whenever you:

Add or remove a status code for:
- /api/nonce
- /api/gate-access
- /api/token-status/{tokenId}
- /api/form-submission-gate
Change the problem+json titles or detail strings you want to commit to.
Adjust the success payloads for gated content or form submission.

Meta-tests in this file

The bottom of contract.test.ts has two project-specific meta-tests:

1. Path coverage

Iterates over all openApiSpec.paths.
Normalizes path params (e.g. {tokenId}) to {param} so /api/token-status/{tokenId} can match.
Collects any documented paths that do not appear in CONTRACT_TESTS as untestedPaths.
Logs a warning and expects untestedPaths length to be 0.

2. Response code coverage

For each path + method pair in the spec, finds the matching ContractTest.
Compares the documented operation.responses keys to the status codes in that contract test.
Builds a missingTests list (e.g. "POST /api/gate-access - Status 418" if that ever showed up).
Logs warnings but doesn’t fail the suite — by design this is informational only.

Coverage helper

The file exports a small generateContractCoverage() utility that prints a project-specific report:

Total endpoints found in openapi.json.
How many of those have a corresponding ContractTest.
A line-by-line list of ✅/❌ METHOD PATH coverage.

You can call this function manually if you ever want ad-hoc visibility into contract coverage.

Summary

This suite is tailored specifically to RitoSwap’s token-gate endpoints, not a generic example.
It encodes the exact success and error shapes for:
- /api/nonce
- /api/gate-access
- /api/token-status/{tokenId}
- /api/form-submission-gate
It uses the same OpenAPI validator as your supertest E2E flow, but runs entirely in Vitest.
Meta-tests and generateContractCoverage() give you a quick read on whether docs and contract tests are still aligned with the public surface area of the project.

API Contract & OpenAPI Testing

What these tests cover

What these tests cover

Endpoint matrix

Endpoint matrix (RitoSwap-specific)

1. GET /api/nonce

2. POST /api/gate-access

3. GET /api/token-status/{tokenId}

4. POST /api/form-submission-gate

How the validator is wired

How the validator is wired (in this repo)

1. Import the validator type

2. Hydrate the spec from public/openapi.json

3. Build mock responses shaped like supertest output

4. Validate per path + method

5. Handle message enums on /api/form-submission-gate

Keeping spec + tests in sync

Keeping spec + tests in sync (RitoSwap workflow)

When to touch contract.test.ts

Meta-tests in this file

1. Path coverage

2. Response code coverage

Coverage helper

Summary

1. `GET /api/nonce`

2. `POST /api/gate-access`

3. `GET /api/token-status/{tokenId}`

4. `POST /api/form-submission-gate`

2. Hydrate the spec from `public/openapi.json`

5. Handle message enums on `/api/form-submission-gate`

When to touch `contract.test.ts`