¿Cómo define OpenAPI los cuerpos de solicitud?

¿Cómo define OpenAPI los cuerpos de solicitud? #

La especificación OpenAPI (OAS) es un método potente para definir API de forma estandarizada e independiente del lenguaje. Uno de los aspectos importantes de esta especificación es la definición de los cuerpos de solicitud. El cuerpo de la solicitud es una parte esencial de una solicitud, en particular en las API RESTful, donde con frecuencia se envían datos complejos a una API para su procesamiento o almacenamiento. Este artículo explora cómo define OpenAPI los cuerpos de solicitud, los distintos componentes que intervienen y las buenas prácticas para su implementación.

Introducción a OpenAPI #

OpenAPI es un estándar ampliamente adoptado para definir API. Permite a los desarrolladores describir los endpoints, los métodos, los parámetros, los cuerpos de solicitud, los formatos de respuesta y más de su API mediante un archivo JSON o YAML. Así se garantiza que las API estén bien documentadas y que tanto otros desarrolladores como las máquinas puedan comprenderlas.

La OpenAPI Initiative, bajo la Linux Foundation, mantiene la especificación OpenAPI. La especificación está diseñada para ser independiente del lenguaje y puede utilizarse para describir API creadas con cualquier tecnología o framework.

Cuerpos de solicitud en OpenAPI #

En el contexto de OpenAPI, un cuerpo de solicitud forma parte de una operación y describe los datos que un servidor espera recibir de un cliente. Esta información es crucial cuando el contenido se envía mediante operaciones como POST, PUT y PATCH, en las que el cliente envía datos al servidor.

El cuerpo de la solicitud se define mediante el objeto requestBody en OpenAPI 3.0 (en OpenAPI 2.0 formaba parte del objeto parameters). El objeto requestBody incluye varias propiedades importantes:

description: una breve explicación del cuerpo de la solicitud.
required: un valor booleano que indica si el cuerpo de la solicitud es obligatorio.
content: un mapa en el que las claves son tipos de medio (media types, p. ej., application/json) y los valores describen los esquemas y los ejemplos de cada tipo de medio.

Definir cuerpos de solicitud #

Ejemplo de definición de un cuerpo de solicitud #

Este es un ejemplo sencillo de la definición de un cuerpo de solicitud en un documento YAML de OpenAPI 3.0:

paths:
  /users:
    post:
      summary: Create a new user
      requestBody:
        description: User object that needs to be added to the database
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: integer
                  example: 1
                name:
                  type: string
                  example: John Doe
                email:
                  type: string
                  format: email
                  example: john.doe@example.com
            examples:
              user:
                summary: A sample user
                value:
                  name: John Doe
                  email: john.doe@example.com
      responses:
        '201':
          description: User created successfully
        '400':
          description: Invalid input

Desglose detallado #

paths: las rutas disponibles de la API, con /users como endpoint.
post: el método HTTP de este endpoint.
summary: una breve descripción de lo que hace esta operación.
requestBody: el objeto que encapsula los datos que se enviarán al servidor.
- description: describe el propósito del cuerpo de la solicitud.
- required: indica que el cuerpo de la solicitud es obligatorio para esta operación.
- content: define el tipo de medio (application/json) y el esquema del cuerpo de la solicitud.
  - schema: describe la estructura del objeto JSON esperado. Incluye las definiciones de las propiedades (id, name, email), sus tipos de datos y ejemplos.
  - examples: proporciona valores de ejemplo para el esquema descrito.

Tipos de medio #

OpenAPI admite una variedad de tipos de medio (media types) para representar los cuerpos de solicitud, lo que garantiza flexibilidad. Algunos tipos de medio comunes son:

application/json
application/xml
multipart/form-data
application/x-www-form-urlencoded

Cada tipo de medio puede tener esquemas y ejemplos distintos para que los clientes sepan cómo estructurar sus solicitudes.

Esquemas #

En OpenAPI, los esquemas definen la estructura de los datos. Se basan en la especificación JSON Schema, pero con algunas extensiones específicas de OpenAPI. Este es un ejemplo de esquema más complejo:

type: object
properties:
  id:
    type: integer
    format: int64
  name:
    type: string
  tag:
    type: string
required:
  - name

Contenido y ejemplos #

La clave content asocia los tipos de medio con sus respectivos esquemas y ejemplos. Así se proporciona un ejemplo para un tipo de medio:

content:
  application/json:
    schema:
      type: object
      properties:
        name:
          type: string
          example: Jane Doe
        age:
          type: integer
          example: 25
    examples:
      user:
        summary: A user example
        value:
          name: Jane Doe
          age: 25

Uso de `requestBody` en escenarios reales #

Crear un recurso nuevo #

Muchas API tienen operaciones para crear recursos nuevos. Por ejemplo, una operación POST sobre /products podría ser así:

paths:
  /products:
    post:
      summary: Add a new product
      requestBody:
        description: Product object that needs to be added
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: integer
                  example: 101
                name:
                  type: string
                  example: "Smartphone"
                price:
                  type: number
                  format: float
                  example: 699.99
      responses:
        '201':
          description: Product created
        '400':
          description: Invalid input

Actualizar un recurso existente #

La actualización de recursos suele usar PUT o PATCH. Este es un ejemplo con PUT:

paths:
  /products/{productId}:
    put:
      summary: Update an existing product
      parameters:
        - name: productId
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        description: Updated product object
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: "Smartphone Pro"
                price:
                  type: number
                  format: float
                  example: 799.99
      responses:
        '200':
          description: Product updated
        '404':
          description: Product not found

En este ejemplo, el método PUT actualiza el producto con el ID especificado (productId).

Funciones avanzadas #

Varios tipos de medio #

Las operaciones pueden admitir varios tipos de medio para un cuerpo de solicitud. Así se define la compatibilidad con JSON y XML:

requestBody:
  description: Example with multiple media types
  content:
    application/json:
      schema:
        type: object
        properties:
          name:
            type: string
            example: "John Doe"
    application/xml:
      schema:
        type: object
        properties:
          name:
            type: string
            example: "John Doe"

Combinación de esquemas #

OpenAPI permite combinar esquemas con las palabras clave allOf, anyOf y oneOf. Esto puede resultar útil para validaciones complejas y para el polimorfismo. Un ejemplo con allOf es:

requestBody:
  content:
    application/json:
      schema:
        allOf:
          - $ref: '#/components/schemas/BaseUser'
          - type: object
            properties:
              email:
                type: string
                format: email
components:
  schemas:
    BaseUser:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string

Buenas prácticas #

Coherencia y reutilización #

Define componentes reutilizables para evitar redundancias y garantizar la coherencia. Usa la sección components de OpenAPI para definir esquemas, parámetros y respuestas que puedan referenciarse en toda la API.

Documentación #

Documenta a fondo los cuerpos de solicitud con descripciones y ejemplos. Esto ayuda a otros desarrolladores a comprender cómo interactuar correctamente con tu API.

Validación #

Usa herramientas que validen tus documentos OpenAPI para asegurarte de que cumplen la especificación y no contienen errores. Herramientas como Swagger Editor, OpenAPI Generator y Stoplight son muy útiles para este fin.

Versionado #

Si tu API evoluciona con el tiempo, usa el versionado en las rutas (/v1/users, /v2/users) para gestionar los cambios incompatibles con versiones anteriores. Esta práctica ayuda a los consumidores de tu API a afrontar los cambios con mayor soltura.

Conclusión #

La especificación OpenAPI ofrece una forma estructurada de definir los cuerpos de solicitud, lo que garantiza que las API sean coherentes, estén bien documentadas y resulten fáciles de usar. Al emplear propiedades como content, schema y examples, los desarrolladores pueden crear definiciones de API completas que facilitan una comunicación fluida entre clientes y servidores. Si sigues las buenas prácticas y aprovechas las herramientas, puedes mejorar la fiabilidad y la usabilidad de tu API.

Para seguir leyendo y consultar más recursos, puedes explorar la especificación OpenAPI oficial y las herramientas disponibles de Swagger y de otros colaboradores.

Con esto concluye la exploración de los cuerpos de solicitud en OpenAPI. ¡Feliz diseño de API!

Última actualización: 21 de mayo de 2024.