{
  "openapi": "3.1.0",
  "info": {
    "title": "Forgejo Zetamind — tickets et projets",
    "description": "Création et suivi de tickets Git sur la forge privée Zetamind. Conçu pour la dictée vocale : créer un ticket, le lister, le commenter, le fermer.",
    "version": "1.0.0"
  },
  "servers": [
    { "url": "https://forgejo.console.zetamind.com/api/v1" }
  ],
  "paths": {
    "/user/repos": {
      "get": {
        "operationId": "listerDepots",
        "summary": "Lister les dépôts accessibles",
        "description": "Retourne les dépôts de l'utilisateur. Utiliser pour connaître les projets disponibles avant de créer un ticket.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Nombre maximum de dépôts (défaut 20).",
            "required": false,
            "schema": { "type": "integer", "default": 20 }
          }
        ],
        "responses": {
          "200": {
            "description": "Liste des dépôts",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "full_name": { "type": "string" },
                      "description": { "type": "string" },
                      "private": { "type": "boolean" },
                      "open_issues_count": { "type": "integer" },
                      "html_url": { "type": "string" }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/repos/{owner}/{repo}/issues": {
      "get": {
        "operationId": "listerTickets",
        "summary": "Lister les tickets d'un dépôt",
        "description": "Retourne les tickets. Par défaut uniquement les tickets ouverts.",
        "parameters": [
          { "name": "owner", "in": "path", "required": true, "description": "Propriétaire du dépôt, par exemple Cedric.", "schema": { "type": "string" } },
          { "name": "repo", "in": "path", "required": true, "description": "Nom du dépôt, par exemple zetamind-context.", "schema": { "type": "string" } },
          { "name": "state", "in": "query", "required": false, "description": "open, closed ou all.", "schema": { "type": "string", "enum": ["open", "closed", "all"], "default": "open" } },
          { "name": "limit", "in": "query", "required": false, "description": "Nombre maximum de tickets (défaut 20).", "schema": { "type": "integer", "default": 20 } }
        ],
        "responses": {
          "200": {
            "description": "Liste des tickets",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/Ticket" }
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "creerTicket",
        "summary": "Créer un ticket",
        "description": "Crée un ticket dans le dépôt indiqué. Le titre doit être court et explicite ; le corps peut contenir du Markdown, y compris des cases à cocher.",
        "parameters": [
          { "name": "owner", "in": "path", "required": true, "description": "Propriétaire du dépôt, par exemple Cedric.", "schema": { "type": "string" } },
          { "name": "repo", "in": "path", "required": true, "description": "Nom du dépôt, par exemple zetamind-context.", "schema": { "type": "string" } }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["title"],
                "properties": {
                  "title": { "type": "string", "description": "Titre court et explicite du ticket." },
                  "body": { "type": "string", "description": "Description en Markdown. Peut contenir des cases à cocher - [ ]." },
                  "labels": {
                    "type": "array",
                    "description": "Identifiants numériques de labels existants.",
                    "items": { "type": "integer" }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Ticket créé",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Ticket" }
              }
            }
          }
        }
      }
    },
    "/repos/{owner}/{repo}/issues/{index}": {
      "get": {
        "operationId": "lireTicket",
        "summary": "Lire un ticket",
        "description": "Retourne le détail d'un ticket, y compris son corps complet.",
        "parameters": [
          { "name": "owner", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "repo", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "index", "in": "path", "required": true, "description": "Numéro du ticket.", "schema": { "type": "integer" } }
        ],
        "responses": {
          "200": {
            "description": "Détail du ticket",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Ticket" }
              }
            }
          }
        }
      },
      "patch": {
        "operationId": "modifierTicket",
        "summary": "Modifier ou fermer un ticket",
        "description": "Met à jour le titre, le corps ou l'état d'un ticket. Utiliser state=closed pour le fermer.",
        "parameters": [
          { "name": "owner", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "repo", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "index", "in": "path", "required": true, "description": "Numéro du ticket.", "schema": { "type": "integer" } }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "title": { "type": "string" },
                  "body": { "type": "string" },
                  "state": { "type": "string", "enum": ["open", "closed"] }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Ticket modifié",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Ticket" }
              }
            }
          }
        }
      }
    },
    "/repos/{owner}/{repo}/issues/{index}/comments": {
      "post": {
        "operationId": "commenterTicket",
        "summary": "Ajouter un commentaire à un ticket",
        "description": "Ajoute un commentaire. Utile pour consigner une avancée sans modifier le corps du ticket.",
        "parameters": [
          { "name": "owner", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "repo", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "index", "in": "path", "required": true, "description": "Numéro du ticket.", "schema": { "type": "integer" } }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["body"],
                "properties": {
                  "body": { "type": "string", "description": "Contenu du commentaire en Markdown." }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Commentaire ajouté",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": { "type": "integer" },
                    "body": { "type": "string" },
                    "html_url": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/repos/{owner}/{repo}/labels": {
      "get": {
        "operationId": "listerLabels",
        "summary": "Lister les labels d'un dépôt",
        "description": "Retourne les labels disponibles avec leur identifiant, à utiliser lors de la création d'un ticket.",
        "parameters": [
          { "name": "owner", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "repo", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Liste des labels",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": { "type": "integer" },
                      "name": { "type": "string" },
                      "color": { "type": "string" }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/user/repos/": {
      "post": {
        "operationId": "creerDepot",
        "summary": "Créer un dépôt (projet)",
        "description": "Crée un nouveau dépôt privé. À utiliser pour démarrer un nouveau projet en mode Git.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["name"],
                "properties": {
                  "name": { "type": "string", "description": "Nom du dépôt, sans espace." },
                  "description": { "type": "string" },
                  "private": { "type": "boolean", "default": true, "description": "Toujours true sauf demande explicite contraire." },
                  "auto_init": { "type": "boolean", "default": true, "description": "Initialise le dépôt avec un README." }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Dépôt créé",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "full_name": { "type": "string" },
                    "html_url": { "type": "string" },
                    "private": { "type": "boolean" }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Ticket": {
        "type": "object",
        "properties": {
          "number": { "type": "integer", "description": "Numéro du ticket." },
          "title": { "type": "string" },
          "body": { "type": "string" },
          "state": { "type": "string" },
          "html_url": { "type": "string", "description": "Lien web du ticket." },
          "created_at": { "type": "string" },
          "labels": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": { "type": "integer" },
                "name": { "type": "string" }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  },
  "security": [ { "bearerAuth": [] } ]
}