Quickstart Guide

This guide walks you through installing the AtoZAPI CLI, scanning an existing codebase, and launching the interactive documentation server.

---

1. Installation

Install the AtoZAPI CLI globally via npm or run it directly using npx:

npm install -g @atozapi/cli

yarn global add @atozapi/cli

pnpm add -g @atozapi/cli

npx @atozapi/cli serve

Verify the installation:

atozapi --help

---

2. Register an Endpoint with Validation

Add an AtoZAPI schema to your route handler. Here is a Node.js Express example:

const express = require('express');
const { atozapi } = require('@atozapi/express');

const app = express();
app.use(express.json());

// 1. Define your schema constraints
const userSchema = {
  name: { type: 'string', required: true, minLength: 2 },
  age: { type: 'number', required: true, min: 18, max: 120 }
};

// 2. Attach atozapi middleware
app.post('/api/users', atozapi(userSchema), (req, res) => {
  const { name, age } = req.validatedBody;
  res.status(201).json({ id: 1, name, age });
});

app.listen(3000, () => {
  console.log('App running on http://localhost:3000');
});

---

3. Launch the Documentation Server

Run the atozapi command in your project root:

atozapi

By default, the engine will: 1. Scan your project files for route definitions and schema declarations. 2. Compile a functional openapi.json matching OpenAPI 3.0.3 standards. 3. Start a local documentation server on port 8000.

Output:

[atozapi] Scanning /path/to/project
[atozapi] Discovered 1 route(s):
  POST   /api/users           (express) -> server.js
[atozapi] Saved OpenAPI specification to openapi.json
[atozapi] Server running on http://localhost:8000
[atozapi] Docs:     http://localhost:8000/docs
[atozapi] ReDoc:    http://localhost:8000/redoc
[atozapi] Spec:     http://localhost:8000/openapi.json

---

4. Explore the Interactive Docs

Open your browser to http://localhost:8000/docs:

• Swagger UI: Test your endpoints interactively using "Try it out".
• Real-Time Validation: The Swagger UI schema displays mandatory fields and numerical/string constraints automatically.
• FastAPI-Standard 422 Schemas: The HTTPValidationError and ValidationError models are linked under each endpoint's response table.

---

5. Generate Spec for CI/CD

To generate the openapi.json contract file without running the HTTP server (e.g. for CI pipelines or static hosting), run:

atozapi generate

This writes the validated spec to ./openapi.json and exits with status code 0.

---

6. Integrating Into an Existing Project (Incremental Adoption)

Adopting AtoZAPI does not require refactoring your existing application:

1. Keep Existing Routes Untouched: AtoZAPI middleware operates per-route. You can adopt it for one new or updated endpoint without affecting existing unannotated routes. 2. Replace Manual Body Checks: Swap out repetitive if (!req.body.name) validation checks or Joi/Celebrate middleware with atozapi(schema). 3. Consume Sanitized Data: Read validated inputs directly from req.validatedBody (Express/Next.js), ginatozapi.BodyT (Go), or $request->attributes->get('validatedBody') (Laravel). 4. Standardized HTTP 422 Errors: Be aware that invalid payloads now automatically return standard HTTP 422 responses formatted identically to FastAPI's { "detail": [...] }. 5. Launch Scanner: Run npx @atozapi/cli in your project root at any time. It will discover all AtoZAPI-guarded endpoints alongside your existing code.