AtoZAPI

Why AtoZAPI?

FastAPI revolutionized the Python world with two core superpowers: declarative runtime validation and instant interactive documentation at /docs.

In other languages, developers are usually stuck maintaining brittle OpenAPI/Swagger YAML annotations, keeping JSDoc comments synchronized, or writing tedious input validation boilerplate.

AtoZAPI eliminates that friction. Write your routes with standard schemas or struct tags:

1. Zero manual Swagger writing: Your route code is the single source of truth.
2. Unified HTTP 422 standard: Every framework returns the exact Pydantic-style { detail: [...] } response.
3. Interactive documentation: Embedded Swagger UI and ReDoc live at http://localhost:8000/docs.

Before vs. After AtoZAPI

Quickstart in 60 Seconds

Run the AtoZAPI scanner anywhere to discover routes, generate openapi.json, and host the Swagger UI server:

# Instant execution with npx
npx @atozapi/cli

# Or install globally
npm install -g @atozapi/cli
atozapi

Output:

[atozapi] Scanning /path/to/project
[atozapi] Discovered 4 route(s):
  POST   /api/users           (express) -> server.js
  POST   /api/products        (nextjs)  -> app/api/products/route.js
  POST   /api/v1/orders       (gin)     -> main.go
  POST   /api/v1/checkout     (laravel) -> app/Http/Controllers/CheckoutController.php
[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

Integrating Into an Existing Project

AtoZAPI is non-invasive and supports incremental, route-by-route adoption:

1. Non-Breaking: Existing unannotated routes in your project remain 100% untouched.
2. Step 1: Install the SDK matching your backend (npm install @atozapi/express, composer require atozapi/laravel, or go get ...).
3. Step 2: Add atozapi(schema) or ginatozapi.Guard(...) to one route to replace manual if (!req.body.name) checks.
4. Step 3: Access validated, typed inputs directly on req.validatedBody or ginatozapi.Body[T](c). Invalid requests automatically receive standard FastAPI-style HTTP 422 errors.
5. Step 4: Run npx @atozapi/cli in your project root to auto-generate openapi.json and view your live Swagger UI.

Schema Reference & Rules

AtoZAPI supports declarative validation constraints across all primitive and complex types:

👉 For full details and examples, visit the Schema Reference Documentation.

Polyglot Ecosystem SDKs

1. Express (Node.js)

npm install @atozapi/express

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

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

const schema = {
  name: { type: 'string', required: true, minLength: 2 },
  age: { type: 'number', required: true, min: 18 }
};

app.post('/api/users', atozapi(schema), (req, res) => {
  res.status(201).json({ user: req.validatedBody });
});

2. Next.js App Router

npm install @atozapi/nextjs

// app/api/users/route.js
import { nextAtozapi } from '@atozapi/nextjs';
import { NextResponse } from 'next/server';

const schema = {
  email: { type: 'string', required: true, pattern: '^[^@]+@[^@]+\\.[^@]+$' },
  age: { type: 'number', required: true, min: 18 }
};

export const POST = nextAtozapi({
  schema,
  handler: async (req, { validatedBody }) => {
    return NextResponse.json({ success: true, user: validatedBody }, { status: 201 });
  }
});

3. Go (Gin)

go get github.com/dhirajparihar/AtoZAPI/sdk-go/gin@v1.0.0

package main

import (
    "net/http"
    ginatozapi "github.com/dhirajparihar/AtoZAPI/sdk-go/gin"
    "github.com/gin-gonic/gin"
)

type CreateUserRequest struct {
    Name string `json:"name" binding:"required,min=2"`
    Age  int    `json:"age"  binding:"required,gte=18"`
}

func main() {
    r := gin.Default()

    r.POST("/api/users", ginatozapi.Guard(CreateUserRequest{}), func(c *gin.Context) {
        user, _ := ginatozapi.Body[CreateUserRequest](c)
        c.JSON(http.StatusCreated, gin.H{"user": user})
    })

    r.Run(":8080")
}

4. PHP (Laravel)

composer require atozapi/laravel

namespace App\Http\Controllers;

use Atozapi\Laravel\Attributes\Post;
use Illuminate\Http\Request;
use Illuminate\Http\JsonResponse;

class UserController
{
    #[Post(
        path: '/api/users',
        summary: 'Create user',
        rules: [
            'name' => 'required|string|min:2',
            'age'  => 'required|integer|min:18'
        ]
    )]
    public function store(Request $request): JsonResponse
    {
        $user = $request->attributes->get('validatedBody');
        return response()->json(['user' => $user], 201);
    }
}

HTTP 422 Error Parity

When validation fails, all AtoZAPI SDKs intercept the request and return the exact Pydantic/FastAPI error format:

{
  "detail": [
    {
      "loc": ["body", "age"],
      "msg": "Input should be greater than or equal to 18",
      "type": "greater_than_equal",
      "ctx": { "ge": 18 }
    },
    {
      "loc": ["body", "email"],
      "msg": "Input should be a valid email address",
      "type": "value_error.email"
    }
  ]
}

Standalone Native Binaries (Zero-Node)

For Go and PHP developers who prefer not to install Node.js or npm, single-file standalone native executables are provided for every release:

Download them directly from the GitHub Releases page:

# Linux / macOS:
curl -LO https://github.com/dhirajparihar/AtoZAPI/releases/latest/download/atozapi-linux-x64
chmod +x atozapi-linux-x64
./atozapi-linux-x64 serve --port 8000

# Windows (PowerShell):
Invoke-WebRequest -Uri "https://github.com/dhirajparihar/AtoZAPI/releases/latest/download/atozapi-win-x64.exe" -OutFile "atozapi.exe"
.\atozapi.exe serve

CLI Options

atozapi [command] [options]

Commands:
  serve       Scan codebase, compile openapi.json, and launch docs server (default)
  generate    Scan codebase and compile openapi.json file only (ideal for CI/CD)

Options:
  -p, --port <number>   Docs server port (default: 8000)
  -d, --dir <path>      Directory to scan for route handlers (default: .)
  -o, --out <path>      Path to output openapi.json (default: ./openapi.json)

Documentation

Full guides, configuration details, and language SDK references are available on our documentation platform: 👉 https://dhirajparihar.github.io/AtoZAPI/

License

MIT © AtoZAPI Authors