openapi: 3.1.0
info:
  title: Catálogo cultural local
  version: 1.0.0
servers:
  - url: https://catalogo.example.test/v1
paths:
  /obras:
    get:
      operationId: listWorks
      summary: Buscar obras del catálogo
      parameters:
        - name: q
          in: query
          required: false
          schema:
            type: string
            minLength: 2
        - name: tipo
          in: query
          required: false
          schema:
            type: string
            enum: [pintura, escultura, fotografia]
        - name: limite
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 20
      responses:
        "200":
          description: Colección filtrada
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkCollection"
        "400":
          description: Parámetro de consulta inválido
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Problem"
  /obras/{work_id}:
    get:
      operationId: getWork
      summary: Consultar una obra
      parameters:
        - name: work_id
          in: path
          required: true
          schema:
            type: string
            pattern: "^wrk-[0-9]+$"
      responses:
        "200":
          description: Obra encontrada
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Work"
        "404":
          description: La obra no existe
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Problem"
components:
  schemas:
    Work:
      type: object
      required: [id, title, type]
      properties:
        id:
          type: string
        title:
          type: string
        type:
          type: string
          enum: [pintura, escultura, fotografia]
        author:
          type: [string, "null"]
        year:
          type: [integer, "null"]
    WorkCollection:
      type: object
      required: [items, total]
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/Work"
        total:
          type: integer
          minimum: 0
    Problem:
      type: object
      required: [code, message]
      properties:
        code:
          type: string
        message:
          type: string