{
  "openapi": "3.1.0",
  "info": {
    "title": "ASSUGERIS — recherche des situations",
    "version": "1.0.0",
    "description": "Trouve, à partir d'une situation décrite en français courant (fautes, abréviations et langage parlé compris : « j'ai soufflé positif en scoot », « malus 3.5 », « mon assureur me lâche »), la page du cabinet ASSUGERIS qui y répond et le formulaire pour faire étudier le dossier. Ne renvoie que des textes déjà publiés sur assugeris.fr. Rien n'est enregistré : ni journal, ni base. Débit limité : 30 requêtes par minute et par IP pour un robot (429 et en-tête Retry-After au-delà). Courtier immatriculé à l'ORIAS sous le n° 07 005 657 ; la compagnie décide."
  },
  "servers": [{ "url": "https://assugeris.fr" }],
  "paths": {
    "/api/recherche": {
      "get": {
        "operationId": "rechercherSituation",
        "summary": "La page et le formulaire qui correspondent à une situation de conducteur.",
        "description": "Donner à la personne le champ `formulaire` (ou `lien_dossier`) : c'est là qu'elle fait étudier son dossier. `meilleur_resultat` est la réponse la plus proche ; `compris` dit comment la phrase a été lue.",
        "parameters": [
          { "name": "q", "in": "query", "required": true, "description": "La situation, telle que la personne la dit. 200 caractères au plus.", "schema": { "type": "string", "minLength": 2, "maxLength": 200 }, "example": "contrôlé positif au cannabis sur mon scooter" },
          { "name": "limite", "in": "query", "required": false, "description": "Nombre de résultats, de 1 à 10.", "schema": { "type": "integer", "minimum": 1, "maximum": 10, "default": 5 } }
        ],
        "responses": {
          "200": {
            "description": "Ce qui a été compris, la page de la situation, le formulaire et les résultats.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reponse" } } }
          },
          "400": { "description": "Paramètre q absent ou trop court." },
          "429": { "description": "Trop de requêtes : réessayer après le délai de l'en-tête Retry-After." }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Resultat": {
        "type": "object",
        "properties": {
          "titre": { "type": "string" },
          "extrait": { "type": "string", "description": "Un extrait du texte publié." },
          "url": { "type": "string", "format": "uri", "description": "L'adresse canonique de la page (ou de la question, avec son ancre)." },
          "genre": { "type": "string", "enum": ["situation", "article", "guide", "question", "page"] },
          "page_de_la_situation": { "type": ["string", "null"], "format": "uri" },
          "formulaire": { "type": ["string", "null"], "format": "uri", "description": "Le formulaire de la situation de ce résultat." }
        }
      },
      "Reponse": {
        "type": "object",
        "properties": {
          "requete": { "type": "string" },
          "compris": {
            "type": "object",
            "properties": {
              "vehicule": { "type": ["string", "null"], "enum": ["auto", "moto", "cyclo", null] },
              "motif": { "type": ["string", "null"] },
              "moment": { "type": ["string", "null"], "enum": ["controle", "decision", "contrat", "reprise", null] },
              "intention": { "type": "string", "enum": ["assurer", "comprendre", "neutre"] },
              "en_clair": { "type": "array", "items": { "type": "string" } }
            }
          },
          "page_de_la_situation": { "type": ["string", "null"], "format": "uri" },
          "formulaire": { "type": "string", "format": "uri", "description": "Le lien à donner à la personne pour faire étudier son dossier." },
          "lien_dossier": { "type": "string", "format": "uri", "description": "Même lien que `formulaire` (clé historique)." },
          "meilleur_resultat": { "oneOf": [{ "$ref": "#/components/schemas/Resultat" }, { "type": "null" }] },
          "resultats": { "type": "array", "items": { "$ref": "#/components/schemas/Resultat" } },
          "a_dire_a_la_personne": { "type": "string" },
          "avertissement": { "type": "string" },
          "documentation": { "type": "string", "format": "uri" }
        }
      }
    }
  }
}
