KoproGo API Specification (OpenAPI 3.0)

Ce dossier contient la spécification OpenAPI 3.0 complète de l’API KoproGo.

📄 Fichiers

openapi.yaml : Spécification OpenAPI 3.0 complète de l’API

🚀 Utilisation

1. Visualiser avec Swagger UI (en ligne)

Ouvrez Swagger Editor et importez le fichier openapi.yaml.

2. Swagger UI local (Docker)

docker run -p 8081:8080 \
  -e SWAGGER_JSON=/api/openapi.yaml \
  -v $(pwd)/docs/api:/api \
  swaggerapi/swagger-ui

Accédez à http://localhost:8081

3. Redoc (alternative élégante)

docker run -p 8082:80 \
  -e SPEC_URL=openapi.yaml \
  -v $(pwd)/docs/api:/usr/share/nginx/html \
  redocly/redoc

Accédez à http://localhost:8082

4. Générer des clients API

TypeScript/JavaScript :

npm install @openapitools/openapi-generator-cli -g
openapi-generator-cli generate \
  -i docs/api/openapi.yaml \
  -g typescript-axios \
  -o frontend/src/lib/api-client

Python :

openapi-generator-cli generate \
  -i docs/api/openapi.yaml \
  -g python \
  -o clients/python

Rust :

openapi-generator-cli generate \
  -i docs/api/openapi.yaml \
  -g rust \
  -o clients/rust

Autres langages supportés : Java, Go, PHP, Ruby, C#, Swift, Kotlin, etc. Liste complète : https://openapi-generator.tech/docs/generators

5. Importer dans Postman/Insomnia

Postman :

Fichier → Import
Sélectionner openapi.yaml
Toutes les requêtes sont créées automatiquement

Insomnia :

Application → Preferences → Data → Import Data
Sélectionner openapi.yaml

📚 Structure de l’API

Tags principaux

Authentication : Login, JWT, switch role
Buildings : Gestion des immeubles
Units : Gestion des lots
Owners : Gestion des copropriétaires
Unit Owners : Relations multi-propriétaires
Expenses : Dépenses et factures (workflow d’approbation)
Accounts : Comptabilité PCMN belge
Financial Reports : Bilan, compte de résultats
Payment Reminders : Relances automatisées (4 niveaux)
Meetings : Assemblées générales
Documents : Gestion documentaire
GDPR : Conformité RGPD (Art. 15, 17, 20)
Health : Monitoring et métriques

Authentification

Toutes les routes (sauf /health) requièrent un JWT Bearer token :

Authorization: Bearer <token>

Obtenir un token :

curl -X POST https://api.koprogo.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "syndic@example.com",
    "password": "secure_password_123"
  }'

Endpoints clés

Bâtiments

GET /buildings - Liste des immeubles
POST /buildings - Créer un immeuble
GET /buildings/{id} - Détails d’un immeuble

Multi-propriétaires

GET /units/{unit_id}/owners - Copropriétaires actifs d’un lot
POST /units/{unit_id}/owners - Ajouter un copropriétaire
GET /units/{unit_id}/owners/total-percentage - Vérifier somme quotes-parts
POST /units/{unit_id}/owners/transfer - Transférer propriété

Workflow dépenses

POST /expenses - Créer dépense (Draft)
PUT /expenses/{id}/submit-for-approval - Soumettre (Draft → PendingApproval)
PUT /expenses/{id}/approve - Approuver (PendingApproval → Approved)
PUT /expenses/{id}/reject - Rejeter avec motif
PUT /expenses/{id}/mark-paid - Marquer comme payée

Comptabilité PCMN

GET /accounts - Liste comptes PCMN
GET /accounts/code/{code} - Recherche par code (ex: 451000)
POST /accounts/seed/belgian-pcmn - Seed 90 comptes PCMN
GET /reports/balance-sheet?year=2025 - Bilan comptable
GET /reports/income-statement?year=2025&quarter=4 - Compte de résultats

Relances de paiement

POST /payment-reminders - Créer relance
PUT /payment-reminders/{id}/escalate - Escalader niveau
GET /payment-reminders/stats - Statistiques recouvrement

🔧 Intégration dans le backend Rust

Option 1 : Service Swagger UI statique

Ajoutez au docker-compose.yml :

services:
  swagger-ui:
    image: swaggerapi/swagger-ui
    container_name: koprogo-swagger-ui
    ports:
      - "8081:8080"
    environment:
      - SWAGGER_JSON=/api/openapi.yaml
      - BASE_URL=/api/docs
    volumes:
      - ./docs/api:/api
    networks:
      - koprogo-network

Option 2 : Intégrer avec utoipa (à venir)

Pour générer automatiquement la spec depuis le code Rust, ajouter au Cargo.toml :

[dependencies]
utoipa = { version = "5.1", features = ["actix_extras", "uuid", "chrono"] }
utoipa-swagger-ui = { version = "8.0", features = ["actix-web"] }

Exemple d’utilisation :

use utoipa::OpenApi;
use utoipa_swagger_ui::SwaggerUi;

#[derive(OpenApi)]
#[openapi(
    paths(
        list_buildings,
        create_building,
        // ... autres endpoints
    ),
    components(
        schemas(Building, CreateBuildingRequest, /* ... */)
    ),
    tags(
        (name = "Buildings", description = "Building management endpoints")
    )
)]
struct ApiDoc;

// Dans main.rs
App::new()
    .service(SwaggerUi::new("/api/docs/{_:.*}")
        .url("/api/docs/openapi.json", ApiDoc::openapi()))

📊 Validation

Validation de la spec

# Avec Spectral
npm install -g @stoplight/spectral-cli
spectral lint docs/api/openapi.yaml

# Avec openapi-generator validator
openapi-generator-cli validate -i docs/api/openapi.yaml

Tests automatisés

Dredd (test contract-driven) :

npm install -g dredd
dredd docs/api/openapi.yaml http://localhost:8080

Schemathesis (property-based testing) :

pip install schemathesis
schemathesis run docs/api/openapi.yaml --base-url http://localhost:8080

📝 Maintenance

Mise à jour de la spec

Lors de l’ajout de nouveaux endpoints :

Ajouter les schémas dans components/schemas
Ajouter les chemins dans paths
Valider avec spectral lint
Tester avec Swagger UI
Commit les changements

Versionning

La spec suit le versionnement sémantique :

Major : Breaking changes (ex: 2.0.0)
Minor : Nouveaux endpoints (ex: 1.1.0)
Patch : Corrections (ex: 1.0.1)

🌐 Déploiement public

La spec OpenAPI sera disponible publiquement à :

Swagger UI : https://api.koprogo.com/docs
ReDoc : https://api.koprogo.com/redoc
Spec JSON : https://api.koprogo.com/openapi.json
Spec YAML : https://api.koprogo.com/openapi.yaml

📚 Ressources

🤝 Contribution

Pour améliorer la spec OpenAPI :

Modifiez openapi.yaml
Validez avec spectral lint
Testez avec Swagger UI local
Créez une pull request

Version : 1.0.0 | Dernière mise à jour : 10 novembre 2025