¿Qué son los componentes reutilizables en OpenAPI?

¿Qué son los componentes reutilizables en OpenAPI? #

La especificación OpenAPI (OAS) es una herramienta potente para definir y documentar API. Funciona como una interfaz estándar para describir API REST y facilita una comunicación clara entre desarrolladores, responsables de producto y otras partes interesadas. Una de las características más útiles de OpenAPI es su compatibilidad con componentes reutilizables. Estos componentes te permiten definir una sola vez los elementos comunes de la especificación de tu API y referenciarlos varias veces, lo que favorece tanto la simplicidad como la coherencia. Este artículo explica qué son los componentes reutilizables en OpenAPI, cuáles son sus ventajas y cómo usarlos de forma eficaz.

Comprender los componentes reutilizables de OpenAPI #

En OpenAPI, los componentes se definen en la sección components. Se pueden reutilizar en toda la especificación de tu API, lo que reduce la redundancia y simplifica notablemente el mantenimiento. Los distintos tipos de componentes reutilizables disponibles en OpenAPI 3.x son:

Esquemas: modelos de datos reutilizables definidos mediante un conjunto de propiedades.
Respuestas: plantillas de respuesta estandarizadas para distintos códigos de estado HTTP.
Parámetros: parámetros comunes de consulta, de ruta y de encabezado.
Ejemplos: ejemplos para respuestas o cuerpos de solicitud.
Cuerpos de solicitud: cargas útiles de solicitud de uso frecuente.
Encabezados: encabezados de uso frecuente.
Esquemas de seguridad: mecanismos de autenticación como claves de API, flujos de OAuth2, etc.
Links: representan relaciones entre operaciones, similares a los hipervínculos de una página web.
Callbacks: solicitudes asíncronas que tu API puede iniciar hacia otros servicios.

Esquemas #

Los esquemas definen la estructura de los datos que tu API envía y recibe. Al crear un esquema como componente reutilizable, garantizas la coherencia entre las distintas partes de tu API que comparten la misma estructura de datos.

Este es un ejemplo:

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          format: int64
        username:
          type: string
        email:
          type: string
        createdAt:
          type: string
          format: date-time

Después puedes referenciar este esquema en las definiciones de tus rutas mediante $ref:

paths:
  /users:
    get:
      summary: Get all users
      responses:
        '200':
          description: A list of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'

Respuestas #

Las respuestas son plantillas reutilizables que definen los códigos de estado de la respuesta y los tipos de contenido. Así puedes definir componentes de respuesta reutilizables:

components:
  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: "Not Found"

Referencia la respuesta anterior en tus rutas:

paths:
  /users/{id}:
    get:
      summary: Get a user by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: A user object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          $ref: '#/components/responses/NotFound'

Parámetros #

Los parámetros de OpenAPI pueden ir en la cadena de consulta, en los encabezados o en la ruta. Suelen reutilizarse en varios endpoints.

Define un parámetro reutilizable:

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

Referencia el parámetro reutilizable:

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

Ejemplos #

Se pueden definir ejemplos reutilizables para proporcionar datos de muestra tanto para las respuestas como para los cuerpos de solicitud.

components:
  examples:
    UserExample:
      summary: A user example
      value:
        id: 1
        username: "johndoe"
        email: "john@example.com"
        createdAt: "2021-06-01T13:15:30Z"

Uso del ejemplo reutilizable:

paths:
  /users:
    get:
      summary: Get all users
      responses:
        '200':
          description: A list of users
          content:
            application/json:
              examples:
                user:
                  $ref: '#/components/examples/UserExample'

Cuerpos de solicitud #

Los cuerpos de solicitud también pueden definirse como componentes reutilizables. Esto resulta especialmente útil cuando varios endpoints aceptan la misma estructura de entrada.

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

Referencia en tus rutas:

paths:
  /users:
    post:
      summary: Create a new user
      requestBody:
        $ref: '#/components/requestBodies/UserInput'
      responses:
        '201':
          description: User created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

Encabezados #

Define encabezados reutilizables que puedan usar varias respuestas o solicitudes:

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

Referencia en tus rutas o respuestas:

paths:
  /users:
    get:
      summary: Get all users
      responses:
        '200':
          description: A list of users
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'

Esquemas de seguridad #

Los esquemas de seguridad reutilizables ayudan a estandarizar los mecanismos de autenticación utilizados en toda la API.

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

Aplica el esquema de seguridad en la sección security:

paths:
  /users:
    get:
      summary: Get all users
      security:
        - bearerAuth: []
      responses:
        '200':
          description: A list of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'

Links #

Los links representan relaciones entre operaciones. Pueden reutilizarse para definir estas relaciones en distintas partes de la especificación de la API.

components:
  links:
    GetUserById:
      operationId: getUserById
      parameters:
        id: '$response.body#/id'

Callbacks #

Los callbacks son, en esencia, operaciones asíncronas que se pueden reutilizar. Resultan útiles en escenarios en los que un gateway de API necesita notificar a otro servicio.

components:
  callbacks:
    onUserCreation:
      '{$request.body#/callbackUrl}':
        post:
          requestBody:
            description: Callback payload
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/User'
          responses:
            '200':
              description: Confirmation of the callback

Las ventajas de los componentes reutilizables #

Coherencia #

Los componentes reutilizables garantizan que las estructuras de datos y los estándares sean coherentes en toda tu API. Por ejemplo, si varios endpoints usan el esquema User, definirlo una sola vez y reutilizarlo evita discrepancias.

Mantenimiento simplificado #

Las actualizaciones resultan más sencillas cuando usas componentes reutilizables. Al cambiar un único componente, los cambios se propagan a todas las instancias que lo referencian. Esta característica es especialmente útil para mantener especificaciones de API grandes y complejas.

Menor redundancia #

La reutilización te permite evitar la duplicación de definiciones similares, lo que hace que la especificación de tu API sea más limpia y fácil de gestionar.

Mejor colaboración #

Al contar con un conjunto estandarizado de componentes reutilizables, los equipos pueden colaborar con mayor eficacia. Todos tendrán la misma visión sobre la estructura y los estándares que se utilizan en toda la API.

Conclusión #

Los componentes reutilizables de OpenAPI ofrecen una forma flexible, coherente y eficiente de gestionar las especificaciones de las API. Aprovechar estas características puede dar lugar a una documentación mejor organizada y más fácil de mantener y, en última instancia, a mejores API. Si aún no utilizas componentes reutilizables, quizá te convenga replantear tu enfoque del diseño de API.

Para obtener más información sobre OpenAPI y los componentes reutilizables, puede resultarte útil la documentación de la especificación OpenAPI. Además, herramientas como Swagger, Redoc y Postman ofrecen formas interactivas de diseñar, implementar y documentar tus API, lo que facilita adoptar los estándares de OpenAPI y beneficiarse de ellos.

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