{
  "openapi": "3.1.0",
  "info": {
    "title": "pragmaBit SDD Generator API",
    "version": "1.0.0",
    "description": "Interfaz sin estado para descubrir preguntas, preparar una vista previa y descargar un paquete documental SDD. Los resultados son borradores y requieren revisión humana."
  },
  "servers": [{ "url": "https://pragmabit.com/sdd-generator" }],
  "paths": {
    "/api/v1/capabilities": {
      "get": {
        "operationId": "getSddCapabilities",
        "summary": "Describe capacidades, tipos y límites del generador",
        "responses": { "200": { "description": "Capacidades", "content": { "application/json": { "schema": { "type": "object" } } } } }
      }
    },
    "/api/v1/questions": {
      "get": {
        "operationId": "getSddQuestions",
        "summary": "Obtiene las preguntas y sus identificadores para un tipo de desarrollo",
        "parameters": [
          { "name": "tipo", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/DevelopmentType" } },
          { "name": "lang", "in": "query", "required": false, "schema": { "type": "string", "enum": ["es", "en"], "default": "es" } }
        ],
        "responses": {
          "200": { "description": "Preguntas", "content": { "application/json": { "schema": { "type": "object", "required": ["tipo", "idioma", "preguntas"], "properties": { "tipo": { "$ref": "#/components/schemas/DevelopmentType" }, "idioma": { "type": "string" }, "preguntas": { "type": "array", "items": { "type": "object" } } } } } } },
          "422": { "$ref": "#/components/responses/ValidationError" }
        }
      }
    },
    "/api/v1/preview": {
      "post": {
        "operationId": "previewSddPackage",
        "summary": "Genera una vista previa JSON sin guardar las respuestas",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Answers" } } } },
        "responses": {
          "200": { "description": "Documentos y pendientes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackagePreview" } } } },
          "415": { "$ref": "#/components/responses/ValidationError" },
          "422": { "$ref": "#/components/responses/ValidationError" }
        }
      }
    },
    "/api/v1/generate": {
      "post": {
        "operationId": "generateSddPackage",
        "summary": "Genera y descarga el ZIP sin guardar las respuestas",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Answers" } } } },
        "responses": {
          "200": { "description": "Paquete ZIP", "content": { "application/zip": { "schema": { "type": "string", "contentEncoding": "binary" } } } },
          "415": { "$ref": "#/components/responses/ValidationError" },
          "422": { "$ref": "#/components/responses/ValidationError" }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "DevelopmentType": { "type": "string", "enum": ["Nuevo", "Evolutivo", "Correctivo", "Migración", "Heredado"] },
      "Requirement": {
        "type": "object",
        "additionalProperties": false,
        "required": ["nombre", "comportamiento", "aceptacion", "error", "prioridad"],
        "properties": {
          "nombre": { "type": "string", "minLength": 1, "maxLength": 2000 },
          "comportamiento": { "type": "string", "minLength": 1, "maxLength": 2000 },
          "aceptacion": { "type": "string", "minLength": 1, "maxLength": 2000 },
          "error": { "type": "string", "minLength": 1, "maxLength": 2000 },
          "prioridad": { "type": "string", "enum": ["Must", "Should", "Could", "Wont"] }
        }
      },
      "Answers": {
        "type": "object",
        "additionalProperties": false,
        "required": ["titulo", "sistema", "tipo", "numero", "clasificacion", "fecha", "campos", "requisitos"],
        "properties": {
          "version": { "type": "integer", "const": 1, "default": 1 },
          "idioma": { "type": "string", "enum": ["es", "en"], "default": "es" },
          "titulo": { "type": "string", "minLength": 1, "maxLength": 200 },
          "sistema": { "type": "string", "minLength": 1, "maxLength": 200 },
          "tipo": { "$ref": "#/components/schemas/DevelopmentType" },
          "numero": { "type": "string", "pattern": "^[0-9]{3}$" },
          "clasificacion": { "type": "string", "enum": ["Pública", "Interna", "Confidencial", "Restringida"] },
          "fecha": { "type": "string", "format": "date" },
          "campos": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 6000 } },
          "requisitos": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/Requirement" } }
        }
      },
      "PackagePreview": {
        "type": "object",
        "required": ["nombre", "archivos", "pendientes"],
        "properties": {
          "nombre": { "type": "string" },
          "archivos": { "type": "object", "additionalProperties": { "type": "string" } },
          "pendientes": { "type": "array", "items": { "type": "object" } }
        }
      },
      "Error": { "type": "object", "required": ["error"], "properties": { "error": { "type": "string" } } }
    },
    "responses": {
      "ValidationError": { "description": "Solicitud no válida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
    }
  }
}