{
  "openapi": "3.0.0",
  "info": {
    "title": "Prisme Education API",
    "description": "API pour accéder aux données Parcoursup filtrées par formation, type de baccalauréat et géographie. Source: Ministère de l'Éducation Nationale - Parcoursup Open Data 2025.",
    "version": "1.0.0",
    "contact": {
      "name": "Prisme Education",
      "url": "https://parcoursup.prisme.education"
    },
    "license": {
      "name": "Open Data",
      "url": "https://parcoursup.prisme.education/api-doc.html"
    }
  },
  "servers": [
    {
      "url": "https://parcoursup.prisme.education",
      "description": "Production server"
    }
  ],
  "paths": {
    "/api/formations": {
      "get": {
        "summary": "Récupérer les formations Parcoursup",
        "description": "Retourne une liste de formations filtrées selon les critères spécifiés (type de bac, recherche, géographie).",
        "operationId": "getFormations",
        "tags": ["Formations"],
        "parameters": [
          {
            "name": "bac",
            "in": "query",
            "description": "Type de baccalauréat",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["general", "technologique", "professionnel"],
              "default": "general"
            }
          },
          {
            "name": "recherche",
            "in": "query",
            "description": "Terme de recherche pour filtrer par nom de formation, filière ou établissement",
            "required": false,
            "schema": {
              "type": "string"
            },
            "examples": {
              "licence": {
                "value": "licence mathematiques",
                "summary": "Recherche de licences de mathématiques"
              },
              "bts": {
                "value": "bts",
                "summary": "Recherche de BTS"
              },
              "ifsi": {
                "value": "ifsi",
                "summary": "Recherche d'IFSI"
              }
            }
          },
          {
            "name": "geo",
            "in": "query",
            "description": "Filtre géographique (ville, académie, région, département)",
            "required": false,
            "schema": {
              "type": "string"
            },
            "examples": {
              "paris": {
                "value": "paris",
                "summary": "Formations à Paris"
              },
              "lyon": {
                "value": "lyon",
                "summary": "Formations à Lyon"
              },
              "bretagne": {
                "value": "bretagne",
                "summary": "Formations en Bretagne"
              }
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Nombre maximum de résultats à retourner",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Liste des formations correspondant aux critères",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FormationsResponse"
                },
                "examples": {
                  "success": {
                    "summary": "Exemple de réponse réussie",
                    "value": {
                      "meta": {
                        "total": 25,
                        "limit": 50,
                        "filters": {
                          "bac": "general",
                          "recherche": "licence mathematiques",
                          "geo": "paris"
                        },
                        "source": "Prisme Education - parcoursup.prisme.education",
                        "data_year": "2025"
                      },
                      "formations": [
                        {
                          "code": "12345",
                          "nom": "Licence - Mathématiques",
                          "etablissement": "Université Paris-Sorbonne",
                          "filiere": "Licence",
                          "academie": "Paris",
                          "ville": "Paris",
                          "departement": "Paris",
                          "region": "Île-de-France",
                          "statut": "Public",
                          "lat": 48.8566,
                          "lng": 2.3522,
                          "stats": {
                            "taux_acces_general": 45,
                            "taux_acces_techno": 12,
                            "taux_acces_pro": 3,
                            "capacite": 150,
                            "effectif_candidats": 2500
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Erreur serveur",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "FormationsResponse": {
        "type": "object",
        "properties": {
          "meta": {
            "type": "object",
            "properties": {
              "total": {
                "type": "integer",
                "description": "Nombre total de formations retournées"
              },
              "limit": {
                "type": "integer",
                "description": "Limite maximale de résultats"
              },
              "filters": {
                "type": "object",
                "properties": {
                  "bac": {
                    "type": "string",
                    "nullable": true
                  },
                  "recherche": {
                    "type": "string",
                    "nullable": true
                  },
                  "geo": {
                    "type": "string",
                    "nullable": true
                  }
                }
              },
              "source": {
                "type": "string",
                "description": "Source des données"
              },
              "data_year": {
                "type": "string",
                "description": "Année des données"
              }
            }
          },
          "formations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Formation"
            }
          }
        }
      },
      "Formation": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "Code unique de la formation"
          },
          "nom": {
            "type": "string",
            "description": "Nom de la formation"
          },
          "etablissement": {
            "type": "string",
            "description": "Nom de l'établissement"
          },
          "filiere": {
            "type": "string",
            "description": "Filière de la formation"
          },
          "academie": {
            "type": "string",
            "description": "Académie"
          },
          "ville": {
            "type": "string",
            "description": "Ville"
          },
          "departement": {
            "type": "string",
            "description": "Département"
          },
          "region": {
            "type": "string",
            "description": "Région"
          },
          "statut": {
            "type": "string",
            "description": "Statut de l'établissement (Public/Privé)"
          },
          "lat": {
            "type": "number",
            "format": "float",
            "description": "Latitude"
          },
          "lng": {
            "type": "number",
            "format": "float",
            "description": "Longitude"
          },
          "stats": {
            "type": "object",
            "nullable": true,
            "properties": {
              "taux_acces_general": {
                "type": "integer",
                "nullable": true,
                "description": "Taux d'accès pour bac général (%)"
              },
              "taux_acces_techno": {
                "type": "integer",
                "nullable": true,
                "description": "Taux d'accès pour bac technologique (%)"
              },
              "taux_acces_pro": {
                "type": "integer",
                "nullable": true,
                "description": "Taux d'accès pour bac professionnel (%)"
              },
              "capacite": {
                "type": "integer",
                "nullable": true,
                "description": "Capacité d'accueil de la formation"
              },
              "effectif_candidats": {
                "type": "integer",
                "nullable": true,
                "description": "Nombre total de candidats"
              }
            }
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "description": "Message d'erreur"
          }
        }
      }
    }
  }
}