¿Qué son los componentes de OpenAPI?

¿Qué son los componentes de OpenAPI? #

OpenAPI, anteriormente conocido como Swagger, es una especificación para definir API en un formato estándar legible por máquinas. Su objetivo es permitir que tanto las personas como las computadoras comprendan las capacidades de un servicio sin necesidad de acceder al código fuente ni a documentación especializada. Una de las características clave que ayudan a lograr este objetivo es el concepto de “componentes”. Este artículo explora qué son los componentes de OpenAPI, por qué son importantes y cómo puedes usarlos de forma eficaz en tus definiciones de API.

Introducción a OpenAPI #

OpenAPI ofrece una forma estándar de documentar las API RESTful. La especificación permite describir la API completa, incluidos los endpoints, los formatos de solicitud y respuesta, los métodos de autenticación y otras características esenciales. La versión 3.0 de la especificación introdujo el concepto de componentes reutilizables, una funcionalidad diseñada para simplificar y modularizar tus definiciones de OpenAPI.

Para comenzar con OpenAPI, consulta la página oficial de la OpenAPI Initiative y la documentación de la especificación OpenAPI (OAS).

¿Qué son los componentes de OpenAPI? #

En el contexto de OpenAPI, los componentes son piezas reutilizables de la definición de tu API. Pueden incluir esquemas (Schemas), respuestas (Responses), parámetros (Parameters), ejemplos (Examples), cuerpos de solicitud (RequestBodies), encabezados (Headers), esquemas de seguridad (SecuritySchemes), links (Links) y callbacks (Callbacks). Los componentes se definen una sola vez y pueden referenciarse varias veces, lo que permite evitar la redundancia y garantizar la coherencia en toda la documentación de tu API.

Tipos de componentes #

A continuación se ofrece un breve resumen de los distintos tipos de componentes de OpenAPI:

  1. Esquemas (schemas): Describen la estructura de los cuerpos de solicitud y respuesta mediante JSON Schema. Un esquema puede definir tanto los tipos de datos como los campos obligatorios y opcionales.

  2. Respuestas (responses): Estas respuestas predefinidas describen cómo se espera que se comporte tu API. Cada respuesta puede incluir un código de estado, una descripción y un esquema.

  3. Parámetros (parameters): Los parámetros definen los valores de entrada que pueden aceptar los endpoints de tu API. Pueden ser parámetros de ruta, de consulta, de encabezado o de cookie.

  4. Ejemplos (examples): Usa ejemplos para ofrecer casos concretos de cómo debe invocarse tu API y qué tipo de respuestas devolverá. Son especialmente útiles para la documentación y las pruebas.

  5. Cuerpos de solicitud (requestBodies): Centraliza las definiciones de tus cuerpos de solicitud, sobre todo cuando varios endpoints utilizan la misma estructura de cuerpo de solicitud.

  6. Encabezados (headers): Define encabezados HTTP reutilizables que pueden emplearse tanto en solicitudes como en respuestas.

  7. Esquemas de seguridad (securitySchemes): Describen los mecanismos de seguridad de tu API, como la autenticación básica, las claves de API o los flujos de OAuth2.

  8. Links (links): Definen posibles relaciones entre recursos y su comportamiento para facilitar la navegación entre ellos.

  9. Callbacks (callbacks): Describen respuestas fuera de banda, como los webhooks o las notificaciones push.

¿Por qué usar los componentes de OpenAPI? #

Usar los componentes de OpenAPI ofrece varias ventajas importantes:

  • Principio DRY: “Don’t Repeat Yourself” (no te repitas). La reutilización ayuda a reducir la redundancia, lo que facilita la gestión y la actualización de tus definiciones de API.
  • Coherencia: Reutilizar componentes garantiza que los elementos comunes, como los esquemas de datos y las definiciones de seguridad, sean coherentes en toda tu API.
  • Claridad: Dividir la especificación de la API en componentes modulares hace que la documentación sea más clara y fácil de entender.
  • Colaboración: Resulta más sencillo que varios desarrolladores trabajen simultáneamente en la definición de la API sin interferir en el trabajo de los demás.

Cómo definir componentes #

Los componentes de OpenAPI se definen bajo el objeto components en el archivo de definición de OpenAPI. A continuación se muestra cómo se puede definir cada tipo de componente.

Esquema #

Un esquema define la estructura de los cuerpos de solicitud y respuesta. Este es un ejemplo:

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          format: int64
        username:
          type: string
        email:
          type: string
      required:
        - id
        - username
        - email

Respuesta #

Un componente de respuesta describe cómo responde tu API a una operación:

components:
  responses:
    NotFound:
      description: Entity not found.
    IllegalInput:
      description: Illegal input for operation.

Parámetro #

Usa componentes de parámetro para definir las entradas de tus endpoints:

components:
  parameters:
    UserId:
      name: id
      in: path
      required: true
      schema:
        type: integer
        format: int64

Ejemplo #

Define ejemplos para ilustrar posibles solicitudes y respuestas de la API:

components:
  examples:
    User:
      summary: A user example
      value:
        id: 123
        username: "john_doe"
        email: "john@example.com"

Cuerpo de solicitud (RequestBody) #

Centraliza las definiciones de tus cuerpos de solicitud para reutilizarlas:

components:
  requestBodies:
    User:
      description: User object
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/User'

Encabezado (Header) #

Usa componentes de encabezado para definir encabezados HTTP comunes:

components:
  headers:
    RateLimit:
      description: The number of allowed requests in the current period
      schema:
        type: integer

Esquema de seguridad (SecurityScheme) #

Describe la configuración de seguridad de tu API:

components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY

Los links establecen relaciones entre las operaciones de la API:

components:
  links:
    UserRepos:
      operationId: getUserRepositories
      parameters:
        username: $response.body#/username

Callback #

Define mecanismos de callback para respuestas asíncronas:

components:
  callbacks:
    NewUserEvent:
      'https://mysite.com/webhook/new-user':
        post:
          requestBody:
            description: Information about the new user
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/User'
          responses:
            '200':
              description: Your server returns this code if the data is received successfully

Referenciar componentes #

Una vez que has definido un componente, puedes referenciarlo mediante la palabra clave $ref. Por ejemplo, para usar un esquema en un endpoint puedes hacer lo siguiente:

paths:
  /users/{id}:
    get:
      summary: Get user by ID
      parameters:
        - $ref: '#/components/parameters/UserId'
      responses:
        '200':
          description: A single user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

Buenas prácticas para usar componentes #

Adoptar algunas buenas prácticas puede ayudarte a sacar el máximo partido de los componentes de OpenAPI:

Centraliza los elementos comunes #

Centraliza los esquemas y parámetros comunes de solicitud y respuesta para agilizar las actualizaciones y garantizar la coherencia. Por ejemplo, los códigos de respuesta comunes como 404 Not Found o los encabezados comunes como Rate-Limit deben definirse una sola vez y reutilizarse.

Usa nombres descriptivos #

Usa nombres descriptivos y significativos para tus componentes, de modo que sean fáciles de identificar. Por ejemplo, en lugar de UserResp, usa UserResponse.

Documenta a fondo #

Incluye descripciones y ejemplos en todos los componentes para mejorar la legibilidad y la utilidad de la documentación de tu API. Las herramientas de documentación autogenerada como Swagger UI pueden aprovechar estos detalles para crear documentación de API interactiva y completa.

Valida con regularidad #

Usa herramientas como Swagger Editor u OpenAPI Generator para validar tu definición de OpenAPI y detectar errores o incoherencias en las primeras etapas del ciclo de desarrollo.

Conclusión #

Los componentes de OpenAPI ofrecen una forma eficaz de modularizar y simplificar tus definiciones de API. Al hacer que tus definiciones sean más mantenibles, reutilizables y coherentes, puedes mejorar tanto la experiencia de los desarrolladores como la de los consumidores. Utilizar los componentes de forma eficaz te permite adherirte a las buenas prácticas y los estándares, lo que hace que tu API sea sólida y mucho más fácil de documentar y gestionar.

Para seguir aprendiendo, te recomendamos profundizar en la documentación de OpenAPI oficial, explorar tutoriales y usar diversas herramientas compatibles con OpenAPI, como SwaggerHub y Postman. Comprender y aprovechar los componentes de OpenAPI puede mejorar significativamente la calidad y la mantenibilidad de tus proyectos de API.

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

Este sitio web no está afiliado a la OpenAPI Initiative.