¿Cuáles son los componentes principales de un documento OpenAPI?

¿Cuáles son los componentes principales de un documento OpenAPI? #

OpenAPI es un potente framework que se utiliza para definir y documentar las API de forma estandarizada. Antes conocido como Swagger, OpenAPI se ha convertido en una herramienta fundamental tanto para desarrolladores como para empresas. Permite desarrollar API fáciles de entender, de consumir y de evolucionar con el tiempo. Pero ¿qué compone un documento OpenAPI? En este artículo analizaremos los componentes principales de un documento OpenAPI, explicando cada parte y su importancia para ayudarte a aprovechar esta herramienta de forma eficaz.

Descripción general de la especificación OpenAPI #

La especificación OpenAPI (OAS) define una forma estándar, independiente del lenguaje, de describir las API RESTful. Permite que tanto las personas como las computadoras comprendan las capacidades de un servicio sin acceder a su código fuente ni a su documentación, ni inspeccionar el tráfico de red. Para obtener más información sobre la especificación en sí, puedes visitar el sitio web de la OpenAPI Initiative.

Componentes principales de un documento OpenAPI #

Un documento OpenAPI tiene una estructura jerárquica que incluye varios componentes clave. Estas son las secciones principales que suelen encontrarse:

Objeto OpenAPI
Objeto Info
Objeto Servers
Objeto Paths
Objeto Components
Objeto Security
Objeto Tags
Objeto External Documentation

Veamos cada uno de estos componentes en detalle.

1. Objeto OpenAPI #

El OpenAPI Object es el objeto raíz del documento OpenAPI. Este objeto es obligatorio e indica la versión de la especificación OpenAPI que sigue el documento.

Ejemplo:

openapi: "3.0.0"

Aquí, el documento cumple con la versión 3.0.0 de la especificación OpenAPI.

2. Objeto Info #

El Info Object proporciona metadatos sobre la API. Incluye información esencial como el título, la descripción, la versión, los términos de servicio, los datos de contacto y la información de la licencia.

Campos obligatorios: #

title: el título de la API.
version: la versión de la API.

Campos opcionales: #

description: una breve explicación de la API.
termsOfService: una URL a los términos de servicio de la API.
contact: información de contacto de los responsables del mantenimiento de la API.
license: la información de la licencia de la API.

Ejemplo:

info:
  title: Sample API
  description: A sample API to illustrate OpenAPI
  version: "1.0.0"
  termsOfService: "https://example.com/terms/"
  contact:
    name: API Support
    url: "https://example.com/support"
    email: support@example.com
  license:
    name: Apache 2.0
    url: "https://www.apache.org/licenses/LICENSE-2.0.html"

3. Objeto Servers #

El Servers Object especifica las URL base de la API. Puede incluir varias URL de servidor, que pueden usarse para distintos entornos (por ejemplo, desarrollo, preproducción y producción).

Ejemplo:

servers:
  - url: "https://api.example.com/v1"
    description: Production server
  - url: "https://sandbox.api.example.com/v1"
    description: Sandbox server

4. Objeto Paths #

El Paths Object contiene las rutas relativas a cada endpoint (elementos de ruta) y sus respectivas operaciones. En resumen, define los endpoints de la API y los métodos HTTP (GET, POST, PUT, DELETE, etc.) que admite cada endpoint.

Ejemplo:

paths:
  /users:
    get:
      summary: Get a list of users
      responses:
        '200':
          description: A JSON array of user names
          content:
            application/json:
              schema: 
                type: array
                items:
                  type: string
  /users/{userId}:
    get:
      summary: Get a user by ID
      parameters:
        - name: userId
          in: path
          required: true
          description: ID of the user to retrieve
          schema:
            type: string
      responses:
        '200':
          description: A single user
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string

5. Objeto Components #

El Components Object es un lugar central para definir esquemas, parámetros, respuestas, ejemplos y otros objetos reutilizables. Esto ayuda a mantener la coherencia y a reducir la redundancia.

Ejemplo:

components:
  schemas:
    User:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: string
        name:
          type: string
  parameters:
    userId:
      in: path
      name: userId
      required: true
      schema:
        type: string
      description: The id of the user

6. Objeto Security #

El Security Object define los esquemas de seguridad que pueden usarse en toda la API. Permite definir varios mecanismos de seguridad, como Basic Auth, claves de API, OAuth2, etc.

Ejemplo:

components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
security:
  - basicAuth: []

7. Objeto Tags #

El Tags Object permite agrupar las operaciones de la API, lo que mejora la legibilidad y la organización. Cada etiqueta puede incluir un nombre y una descripción opcional.

Ejemplo:

tags:
  - name: user
    description: Operations related to users
  - name: admin
    description: Operations for admin users

8. Objeto External Documentation #

El External Documentation Object proporciona referencias a documentación adicional, con información complementaria que no puede incluirse en el documento OpenAPI principal.

Ejemplo:

externalDocs:
  description: Find more info here
  url: "https://example.com/docs"

Componentes adicionales #

Aunque los componentes principales son necesarios para que un documento OpenAPI sea funcional, existen secciones opcionales que pueden añadirse para obtener capacidades más avanzadas.

1. Callbacks #

El Callbacks Object describe las solicitudes salientes que un proveedor de API enviará a un cliente en respuesta a determinadas operaciones.

2. Links #

El Links Object representa posibles relaciones entre las respuestas y otras operaciones. Esto puede ayudar a crear una experiencia de API más interactiva e intuitiva.

3. Ejemplos #

El Examples Object permite definir distintos ejemplos que pueden reutilizarse en toda la documentación de la API, lo que facilita la comprensión de la estructura y del contenido esperados.

Herramientas y recursos #

Existen numerosas herramientas para ayudarte a crear, validar y visualizar documentos OpenAPI. Estos son algunos recursos y herramientas útiles:

Swagger Editor: una herramienta web para escribir definiciones OpenAPI.
Postman: una plataforma de colaboración para el desarrollo de API que admite OpenAPI.
Redoc: una herramienta de código abierto para generar documentación de API a partir de definiciones OpenAPI.

Conclusión #

OpenAPI ofrece una forma sistemática y estandarizada de definir y documentar las API, lo que facilita que los desarrolladores, las partes interesadas e incluso las herramientas automatizadas interactúen con lo que ofrece una API y lo comprendan. Entender los componentes principales de un documento OpenAPI, como el objeto OpenAPI, el objeto Info, el objeto Servers, el objeto Paths y otros, es el primer paso para aprovechar todo el potencial de los estándares de API y mejorar el ciclo de vida del desarrollo de API.

Para profundizar más en OpenAPI, puedes consultar la especificación OpenAPI oficial u otras herramientas de documentación sólidas como Swagger y Redoc.

Al comprender la estructura y la finalidad de cada componente, estarás en buen camino para crear API que no solo sean funcionales, sino también comprensibles y fáciles de mantener.

Esperamos que este análisis detallado de los componentes principales de un documento OpenAPI te resulte útil. Comprender estos elementos es fundamental para cualquier persona que participe en el desarrollo de API, ya que hace que tus API sean más robustas, más fáciles de usar y más sencillas de mantener.

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