¿Cómo se definen las operaciones en OpenAPI?

¿Cómo se definen las operaciones en OpenAPI? #

OpenAPI, antes conocido como Swagger, es un estándar consolidado diseñado para describir, producir, consumir y visualizar servicios web RESTful. Uno de los componentes clave de OpenAPI es la especificación de las operaciones. Estas operaciones son, en esencia, endpoints individuales de la API que representan una funcionalidad concreta expuesta por el servicio.

En este artículo exploraremos cómo se definen las operaciones en OpenAPI. Analizaremos la estructura básica, los componentes y los atributos detallados que permiten describir de forma completa una operación dentro de tu documento OpenAPI.

Estructura básica #

Un documento OpenAPI es un archivo JSON o YAML que incluye toda la información necesaria sobre las operaciones de la API. Estas operaciones se definen dentro de la sección paths del documento. Aquí, cada ruta corresponde a un endpoint específico y contiene una o más operaciones (por ejemplo, GET, POST, PUT, DELETE).

A continuación se muestra un ejemplo básico en formato YAML:

openapi: 3.0.0
info:
  version: 1.0.0
  title: Sample API
paths:
  /users:
    get:
      summary: Get All Users
      responses:
        '200':
          description: A list of users.
  /users/{id}:
    get:
      summary: Get User by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A user object.

En este ejemplo, hemos definido dos endpoints: /users y /users/{id}, cada uno con una operación GET.

Objeto Path Item #

El objeto paths contiene varios objetos Path Item. Cada objeto Path Item describe las operaciones disponibles en una única ruta. Por ejemplo, la ruta /users incluye una operación bajo la clave get, que define el comportamiento de la solicitud GET en esa ruta.

Parámetros de ruta #

Algunas rutas pueden incluir parámetros, indicados mediante llaves {} en la cadena de la ruta. En el ejemplo anterior, /users/{id} contiene un parámetro de ruta id. Los parámetros de ruta son obligatorios y se definen dentro de la sección parameters de cada operación.

Objeto Operation #

El núcleo de una operación de OpenAPI está representado por el objeto Operation. Este objeto incluye varios campos que describen la operación en detalle. Los campos más utilizados son:

summary: un breve resumen de lo que hace la operación.
description: una descripción más extensa de la funcionalidad de la operación.
parameters: un arreglo (array) de parámetros que acepta la operación.
requestBody: el cuerpo de la solicitud, usado principalmente en las operaciones POST, PUT y PATCH.
responses: una colección de las posibles respuestas que devuelve la operación.
tags: un arreglo de etiquetas para controlar la documentación de la API.
operationId: un identificador único de la operación.
security: los requisitos de seguridad de la operación.

Parámetros #

Los parámetros definen las entradas que requiere una operación. Pueden aparecer en distintas ubicaciones, como la consulta (query), los encabezados (header), la ruta (path) o las cookies (cookie).

A continuación se muestra un ejemplo de una operación GET con parámetros de consulta:

paths:
  /users:
    get:
      summary: Get All Users
      parameters:
        - name: limit
          in: query
          description: Maximum number of users to return
          required: false
          schema:
            type: integer
        - name: offset
          in: query
          description: Pagination offset
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: A list of users.

Cuerpo de la solicitud #

La sección requestBody se usa para describir el contenido de una solicitud en operaciones como POST, PUT y PATCH. Define el esquema y las propiedades de los datos que se envían al servidor.

Ejemplo de una operación POST con un requestBody:

paths:
  /users:
    post:
      summary: Create a User
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - username
                - email
              properties:
                username:
                  type: string
                email:
                  type: string
      responses:
        '201':
          description: User created successfully.

Respuestas #

El objeto responses describe las posibles respuestas que puede devolver una operación. Cada respuesta se identifica por su código de estado HTTP (por ejemplo, 200, 404). El objeto de respuesta puede incluir una description y, opcionalmente, una sección content que especifica el tipo de medio y el esquema del cuerpo de la respuesta.

Ejemplo de una sección de respuestas:

paths:
  /users/{id}:
    get:
      summary: Get User by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A user object.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  username:
                    type: string
                  email:
                    type: string
        '404':
          description: User not found.

Etiquetas #

Las etiquetas se usan para categorizar las operaciones y facilitar la navegación. Cada operación puede incluir un arreglo de etiquetas, y estas etiquetas pueden referenciarse en la documentación de OpenAPI.

Ejemplo:

paths:
  /pets:
    get:
      tags:
        - Pets
      summary: Get All Pets
      responses:
        '200':
          description: A list of pets.

OperationId #

El operationId es una cadena única que se utiliza para identificar una operación. Resulta especialmente útil para la generación de código y las bibliotecas de cliente, ya que proporciona una referencia estable a la operación.

Ejemplo:

paths:
  /users:
    get:
      operationId: getUsers
      summary: Get All Users
      responses:
        '200':
          description: A list of users.

Seguridad #

La sección security especifica los mecanismos de seguridad necesarios para ejecutar la operación. Estos pueden incluir claves de API, flujos de OAuth2, entre otros.

Ejemplo:

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
paths:
  /users:
    get:
      security:
        - ApiKeyAuth: []
      summary: Get All Users
      responses:
        '200':
          description: A list of users.

Reutilización con componentes #

OpenAPI admite la reutilización mediante la sección components. Los elementos de uso común, como esquemas, respuestas y parámetros, pueden definirse una sola vez y referenciarse varias veces.

Ejemplo de componentes reutilizables:

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
        username:
          type: string
        email:
          type: string
  responses:
    UserNotFound:
      description: User not found.
paths:
  /users/{id}:
    get:
      summary: Get User by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A user object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          $ref: '#/components/responses/UserNotFound'

En este ejemplo, el esquema User y la respuesta UserNotFound se definen en la sección components y luego se referencian en las rutas, lo que garantiza la coherencia y reduce la redundancia.

Conclusión #

Definir operaciones en OpenAPI implica una estructura completa que incluye rutas, parámetros, cuerpos de solicitud, respuestas y varios otros atributos. Al aprovechar las funciones de organización y reutilización de OpenAPI, puedes crear documentación de API clara y fácil de mantener.

Ya seas diseñador de API, desarrollador o consumidor, comprender cómo se definen las operaciones en OpenAPI puede mejorar enormemente tu capacidad para trabajar con servicios web modernos.

Para obtener más información, puedes consultar la documentación de la especificación OpenAPI. Herramientas como Swagger y Redoc pueden ayudarte aún más a crear y visualizar documentos OpenAPI.

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