petitspas/api-contracts

📜 API Contracts - PtitsPas

Ce dossier contient les contrats d'API qui définissent les interfaces entre les différentes couches de l'application.

🎯 Objectif

Garantir que Frontend, Backend et Database respectent des contrats stricts, permettant de les rendre interchangeables sans casser l'application.

---

📁 Structure

api-contracts/
├── frontend-backend/          # Contrat Frontend ↔ Backend (HTTP REST)
│   ├── openapi.yaml          # Spécification OpenAPI 3.0 (source de vérité)
│   └── generated/            # Code généré automatiquement
│       ├── dart/             # Client API pour Flutter
│       └── typescript/       # Types pour NestJS
│
└── backend-database/          # Contrat Backend ↔ Database (ORM/SQL)
    ├── schema.prisma         # Schéma Prisma (ou TypeORM entities)
    └── migrations/           # Migrations SQL versionnées

---

🔄 Workflow de Génération

1. Frontend ↔ Backend

Source de vérité : frontend-backend/openapi.yaml

Génération du client Dart (Flutter) :

cd api-contracts/frontend-backend
docker run --rm -v "${PWD}:/local" openapitools/openapi-generator-cli generate \
  -i /local/openapi.yaml \
  -g dart-dio \
  -o /local/generated/dart

Génération des types TypeScript (NestJS) :

cd api-contracts/frontend-backend
npx openapi-typescript openapi.yaml --output generated/typescript/api.types.ts

---

2. Backend ↔ Database

Source de vérité : backend-database/schema.prisma

Génération du client Prisma :

cd api-contracts/backend-database
npx prisma generate

Génération des migrations SQL :

cd api-contracts/backend-database
npx prisma migrate dev --name <nom_migration>

---

✅ Avantages

• Frontend interchangeable : React, Vue, Angular → il suffit de régénérer le client API
• Backend interchangeable : Python, Go, Java → tant qu'il respecte openapi.yaml
• Database read-only en prod : User PostgreSQL app_user (pas de DDL)
• Cohérence garantie : Types générés = pas d'erreur de typage
• Documentation auto : OpenAPI = documentation interactive (Swagger UI)

---

📚 Documentation

• OpenAPI 3.0 Spec
• Prisma Schema
• openapi-generator
• openapi-typescript