Laboratorio ejecutable · Bloque 1

EX-B1-05

Leer una API desde OpenAPI

Debes preparar una integración con un catálogo cultural, pero solo dispones de un documento OpenAPI acotado. La interfaz gráfica no está disponible.

Escribir y ejecutar código
Implementación contract-first
Básica
Apoyo moderado
Starter ejecutable

Cómo abordarla

Observa el fundamento construyendo una API

Descarga el starter, predice un resultado, ejecuta, modifica la API y vuelve a observar. La explicación breve acompaña al código; no lo sustituye.

Abrir laboratorio de código

1. Descarga y arranca

Starter contract-firstContrato, aplicación parcial, datos locales y tests de conformidad visibles.
Contrato OpenAPIEspecificación local, reducida y válida para un catálogo cultural ficticio.
Cuestionario de lecturaPreguntas sobre operaciones, parámetros, schemas y respuestas.

2. Escribe y prueba

Ejecuta la suite y extrae del OpenAPI la matriz de operaciones que debes preservar.
Implementa `GET /works` con `q`, `type` y `limit`, incluido el rechazo de parámetros fuera del contrato.
Implementa `GET /works/{work_id}` con patrón de identificador, respuesta pública y 404 estable.
Compara `/openapi.json` con el contrato fuente y añade una prueba negativa por operación.

3. Demuestra el comportamiento

API ejecutable con las dos operaciones y tests de conformidad verdes.
Matriz contrato → implementación → test para parámetros, 200, 400 y 404.
Captura de una búsqueda y un 404 obtenidos contra Uvicorn.

La respuesta principal es tu código y sus pruebas. Usa este espacio solo para anotar la predicción inicial y el resultado observado.

Predicción breve antes de ejecutar

Antes de programar, ¿qué rutas, parámetros y status deberá exponer tu implementación para no divergir del OpenAPI?

Documento OpenAPI

openapi: 3.1.0
info:
  title: Local culture catalog
  version: 1.0.0
servers:
  - url: https://catalog.example.test/v1
paths:
  /works:
    get:
      operationId: listWorks
      summary: Search catalog works
      parameters:
        - name: q
          in: query
          required: false
          schema:
            type: string
            minLength: 2
        - name: type
          in: query
          required: false
          schema:
            type: string
            enum: [painting, sculpture, photograph]
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 20
      responses:
        "200":
          description: Filtered collection
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkCollection"
        "400":
          description: Invalid query parameter
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Problem"
  /works/{work_id}:
    get:
      operationId: getWork
      summary: Get a work
      parameters:
        - name: work_id
          in: path
          required: true
          schema:
            type: string
            pattern: "^wrk-[0-9]+$"
      responses:
        "200":
          description: Work found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Work"
        "404":
          description: Work not found
          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: [painting, sculpture, photograph]
        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

Comprueba estas tres cosas

Localiza la URL base, la ruta, el método y los parámetros disponibles.
Distingue qué parámetros son opcionales y qué límites tienen.
Describe una respuesta satisfactoria y un error siguiendo los schemas referenciados.

Bitácora breve

Anota predicción, comando ejecutado y diferencia observada; el código vive en tu workspace.

Sin respuesta guardada.

Pistas opcionales

Pista 1 · Recorre el contrato en capas

Empieza por servers y paths; después baja a cada método, parameters y responses.
Deja components para cuando encuentres una referencia.

Pista 2 · Separa descripción y restricción

Una descripción explica intención; type, enum, minimum y required restringen valores.

Profundización opcional

Traducir un OpenAPI 3.1 acotado a una API FastAPI ejecutable sin cambiar el contrato público.

Contexto adicional

El contrato contiene una consulta de colección y una consulta individual.
No se pide implementar un cliente ni memorizar toda la especificación OpenAPI.
Cada afirmación debe señalar el elemento del contrato que la respalda.

Cómo revisar tu respuesta

Los parámetros de path y query no se intercambian.
La obligatoriedad se obtiene de required y no de la intuición.
Las referencias $ref se siguen hasta el schema correspondiente.
La lectura funciona sin depender de Swagger UI.
Métodos y paths del OpenAPI generado coinciden con el documento fuente.

Evidencia, revisión y reinicio

Dos operaciones FastAPI implementadas desde el contrato.
Comparación automática entre rutas, parámetros, status y schemas esperados y generados.

Revisión: con Codex, utilizando la evidencia y los criterios anteriores; no se publica una solución oficial.

Reinicio: Eliminar el workspace temporal y volver a extraer el ZIP.

¿Qué quieres consultar?