Julien Martin
aa61831878
- Contrats d'API Frontend ↔ Backend (OpenAPI 3.0) - Contrats Backend ↔ Database (Prisma/SQL) - Documentation complète pour génération de code - Permet l'interchangeabilité des composants
86 lines
2.5 KiB
Markdown
86 lines
2.5 KiB
Markdown
# 📜 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) :**
|
|
```bash
|
|
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) :**
|
|
```bash
|
|
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 :**
|
|
```bash
|
|
cd api-contracts/backend-database
|
|
npx prisma generate
|
|
```
|
|
|
|
**Génération des migrations SQL :**
|
|
```bash
|
|
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](https://swagger.io/specification/)
|
|
- [Prisma Schema](https://www.prisma.io/docs/concepts/components/prisma-schema)
|
|
- [openapi-generator](https://openapi-generator.tech/)
|
|
- [openapi-typescript](https://github.com/drwpow/openapi-typescript)
|
|
|