dApp API Overview

This section describes how the RitoSwap dApp APIs are put together and how the individual endpoint pages (Token Status, Nonce, Gate Access, Form Submission Gate, Logger) relate to the underlying code.

The goal of this page is to give contributors a mental model:

• Where the API handlers live
• How request/response contracts are defined
• How the OpenAPI spec is generated from Zod
• How everything is deployed as Next.js + Vercel serverless functions
• How the APIs are covered by Vitest (unit/integration) and Supertest (E2E)

Each route then has its own dedicated MDX page for deeper, endpoint‑specific details.

Runtime & hosting

The dApp API surface is implemented using the Next.js App Router and deployed as Vercel serverless functions.

Each HTTP endpoint documented in this section corresponds directly to a Next.js route.ts file under dapp/app/api. The docs on this site are meant to describe behavior and usage, while the OpenAPI spec is the single source of truth for the exact contracts.

Schema-first API design with Zod & OpenAPI

All request/response contracts are defined with Zod v4 and converted into an OpenAPI document with @asteasolutions/zod-to-openapi.

Key packages:

Directory layout for schemas:

• dapp/app/schemas

At a high level:

• Domain schemas (dapp/app/schemas/domain) capture core business rules independent of transport (validation helpers, shared guards, value objects).
• DTO schemas (dapp/app/schemas/dto) describe the HTTP layer (request bodies, query params, path params, and responses per route).
• OpenAPI schemas (dapp/app/schemas/openapi) stitch the domain/DTO schemas into a full OpenAPI document.

extendZodWithOpenApi

The OpenAPI pipeline is built around extendZodWithOpenApi, which augments the Zod namespace with OpenAPI metadata helpers.

Typical pattern:

1. Extend Zod: Call extendZodWithOpenApi(z) once in the OpenAPI bootstrap file.
2. Annotate schemas: Tag DTO/domain schemas with OpenAPI metadata (examples, descriptions, parameter hints).
3. Generate spec: Use generateOpenApiDocument (or equivalent) to emit a full openapi.json into public/.
4. Serve spec: /api/openapi reads that JSON, adjusts the servers array based on the current request/host, and returns it.

In other words: Zod is the single source of truth, and OpenAPI/Swagger are derived artifacts.

Documentation surfaces

There are two layers of documentation for the dApp APIs:

1. Human-friendly MDX pages (this section)

   • One page per major route: Token Status, Nonce Generation, Gate Access, Form Submission Gate, Logger.
   • Focused on concepts, when-to-use guidance, gotchas, and examples.

2. Machine-readable OpenAPI + Swagger UI

   • Generated spec at /api/openapi (served by dapp/app/api/openapi/route.ts).
   • Full-page Swagger console at /api-docs (dapp workspace).

• Embedded Swagger blocks in the docs site via <SwaggerDocs /> or <SwaggerDocs tag="..." />.

The embedded component lives at:

// docs/app/components/utilities/swaggerdocs/SwaggerDocs.tsx
<SwaggerUI
  url={`${apiBaseUrl}/api/openapi`}
  tryItOutEnabled
  docExpansion="none"
  defaultModelsExpandDepth={-1}
  filter={tag || undefined}
/>

On this docs site, endpoint pages use the tag filter (for example, "Token Status" or "Gate Access") to show only the relevant slice of the spec.

Testing strategy

The dApp APIs are covered at multiple levels, from pure schema tests to live HTTP calls.

Unit & integration — Vitest

Key packages:

Vitest is used to:

• Assert that domain/DTO schemas accept valid payloads and reject invalid ones.
• Exercise helper libraries (logging, signing, rate-limiting, etc.).
• Validate that OpenAPI generation doesn’t drift from the Zod schemas.

End-to-end API tests — Supertest

For live HTTP behavior, the project uses Supertest:

These tests:

• Spin up the API routes and hit them over HTTP (or equivalent handler adapters).
• Validate end-to-end behavior including status codes, headers, and RFC 7807 error shapes.
• Are especially important for routes like /api/gate-access and /api/form-submission-gate, which combine auth, chain reads, database access, and side effects.

See the Testing & QA → Supertest docs for concrete test locations and scenarios.

Endpoint index

Use the table below as the high-level map for the API docs in this section.

How to extend the API surface

When adding a new endpoint:

This keeps schemas, handlers, docs, and tests aligned while letting the OpenAPI spec remain the canonical contract for clients.

```js
// docs/content/dapp/api/_meta.js

const meta = {
  index: 'Overview',
  'token-status': 'Token Status',
  nonce: 'Nonce Generation',
  'gate-access': 'Gate Access',
  'form-submission-gate': 'Form Submission Gate',
  logger: 'Logger',
};

export default meta;