{
  "openapi": "3.0.3",
  "info": {
    "title": "APCM - Escalas API",
    "description": "API pública de escalas marítimas de la Autoridad Portuaria de Costa Marina (APCM). Permite consultar las escalas de buques, información de los buques y los muelles operativos del puerto.",
    "version": "1.0.0",
    "contact": {
      "name": "APCM Innovación",
      "email": "innovacion@apcm.example"
    },
    "license": {
      "name": "CC BY 4.0",
      "url": "https://creativecommons.org/licenses/by/4.0/"
    }
  },
  "servers": [
    {
      "url": "https://api.apcm.example/v1",
      "description": "Producción"
    }
  ],
  "tags": [
    {
      "name": "Escalas",
      "description": "Consulta de escalas portuarias"
    },
    {
      "name": "Buques",
      "description": "Información de los buques"
    },
    {
      "name": "Muelles",
      "description": "Muelles e infraestructura portuaria"
    }
  ],
  "paths": {
    "/escalas": {
      "get": {
        "tags": [
          "Escalas"
        ],
        "summary": "Lista de escalas",
        "description": "Devuelve un listado paginado de escalas, con filtros opcionales.",
        "operationId": "listEscalas",
        "parameters": [
          {
            "name": "fecha_desde",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "Fecha de llegada mínima (YYYY-MM-DD)"
          },
          {
            "name": "fecha_hasta",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "Fecha de llegada máxima (YYYY-MM-DD)"
          },
          {
            "name": "tipo_buque",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "Container Ship",
                "Bulk Carrier",
                "Tanker",
                "Ro-Ro",
                "Cruise",
                "General Cargo"
              ]
            }
          },
          {
            "name": "muelle",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50,
              "minimum": 1,
              "maximum": 500
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0,
              "minimum": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Escala"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Parámetros inválidos",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/escalas/{id_escala}": {
      "get": {
        "tags": [
          "Escalas"
        ],
        "summary": "Detalle de una escala",
        "operationId": "getEscala",
        "parameters": [
          {
            "name": "id_escala",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "ESC-2024-00123"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Escala"
                }
              }
            }
          },
          "404": {
            "description": "No encontrada",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/buques/{imo}": {
      "get": {
        "tags": [
          "Buques"
        ],
        "summary": "Detalle de un buque por IMO",
        "operationId": "getBuque",
        "parameters": [
          {
            "name": "imo",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1000000,
              "maximum": 9999999
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Buque"
                }
              }
            }
          },
          "404": {
            "description": "No encontrado",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/muelles": {
      "get": {
        "tags": [
          "Muelles"
        ],
        "summary": "Lista de muelles operativos",
        "operationId": "listMuelles",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Muelle"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Escala": {
        "type": "object",
        "required": [
          "id_escala",
          "imo",
          "muelle",
          "fecha_llegada"
        ],
        "properties": {
          "id_escala": {
            "type": "string",
            "example": "ESC-2024-00123"
          },
          "imo": {
            "type": "integer",
            "example": 9431071
          },
          "nombre_buque": {
            "type": "string",
            "example": "Mediterranean Aurora"
          },
          "tipo_buque": {
            "type": "string",
            "example": "Container Ship"
          },
          "bandera": {
            "type": "string",
            "example": "Malta"
          },
          "muelle": {
            "type": "string",
            "example": "Terminal Contenedores TC-1"
          },
          "fecha_llegada": {
            "type": "string",
            "format": "date-time"
          },
          "fecha_salida": {
            "type": "string",
            "format": "date-time"
          },
          "puerto_origen": {
            "type": "string",
            "example": "Valencia"
          },
          "puerto_destino": {
            "type": "string",
            "example": "Génova"
          }
        }
      },
      "Buque": {
        "type": "object",
        "required": [
          "imo",
          "nombre"
        ],
        "properties": {
          "imo": {
            "type": "integer"
          },
          "mmsi": {
            "type": "integer"
          },
          "nombre": {
            "type": "string"
          },
          "tipo": {
            "type": "string"
          },
          "bandera": {
            "type": "string"
          },
          "eslora_m": {
            "type": "number"
          },
          "manga_m": {
            "type": "number"
          },
          "gt": {
            "type": "integer",
            "description": "Gross Tonnage"
          }
        }
      },
      "Muelle": {
        "type": "object",
        "required": [
          "codigo",
          "nombre"
        ],
        "properties": {
          "codigo": {
            "type": "string",
            "example": "TC-1"
          },
          "nombre": {
            "type": "string",
            "example": "Terminal Contenedores TC-1"
          },
          "longitud_m": {
            "type": "number",
            "example": 650
          },
          "calado_m": {
            "type": "number",
            "example": 16.5
          },
          "usos": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "Contenedores"
            ]
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "code",
          "message"
        ],
        "properties": {
          "code": {
            "type": "string",
            "example": "NOT_FOUND"
          },
          "message": {
            "type": "string",
            "example": "Recurso no encontrado"
          }
        }
      }
    }
  }
}