Especificación OpenAPI para documentar APIs RESTful

Contenido del curso

Introducción y Fundamentos de API First

Herramientas y Validación de APIs

Versionado, Prototipado y Documentación

Validación y Pruebas de Contratos

Seguridad

19
Proteger endpoints con JWT en OpenAPI
07:40 min

Tomar examen

Cursos Empresas Blog Live Conf Eventos Precios

0:007:38

Especificación OpenAPI para documentar APIs RESTful

Curso de API First

Clase 2 de 19

Clase 2 / 19

Recursos

La iniciativa OpenAPI (conocida previamente como Swagger) se ha convertido en una especificación fundamental para documentar APIs RESTful efectivamente. Gracias a un formato sencillo, estandarizado y legible a través de archivos YML, permite tanto a desarrolladores como a otros sistemas informáticos comprender las características y capacidades de una API específica. Facilita drásticamente el desarrollo, consumo y mantenimiento de las APIs.

¿Qué es OpenAPI y para qué sirve?

OpenAPI es una especificación enfocada en documentar APIs con la intención de que humanos y máquinas interpreten fácilmente las funcionalidades disponibles. Cuenta con una estructura clara basada en archivos YML incluidos directamente en tu proyecto, proporcionándote:

Documentación automática y actualizada.
Generación automática y precisa de código.
Facilitación del control y validación de solicitudes y respuestas.
Colaboración eficiente entre distintos equipos.
Mejor adopción e implementación de servicios API.

¿Cómo se estructura un archivo OpenAPI YML?

La estructura del archivo OpenAPI incluye algunos bloques esenciales indispensables para su correcta comprensión y uso:

Versión e información general

Define la versión específica de OpenAPI que utilizas (actualmente 3.1.1) y un bloque informativo con:

Título descriptivo de tu API.
Descripción funcional.
Información detallada de contacto para consultas internas o externas del proyecto.

Servidores disponibles

Aquí especificas direcciones URL relevantes:

Servidor de producción.
Servidor para pruebas o staging.

Definición de rutas (paths)

Los paths permiten detallar cada endpoint y operación que tu API manejará:

Métodos como GET o POST determinan tipos específicos de operación.
Parámetros, descripción, esquema y requerimientos se detallan explícitamente por método.
Posibles respuestas HTTP definidas claramente, mostrando el tipo de datos esperado y esquemas específicos.

Componentes reutilizables

Componentes es un bloque que estructura plantillas reutilizables, como:

Esquemas compartidos como el usuario, con propiedades (ID, nombre, email).
Configuraciones generales de seguridad aplicables a distintas partes de tu API.

¿Cuáles son las principales ventajas prácticas al implementar OpenAPI?

La implementación de OpenAPI tiene beneficios claros y comprobados:

Facilita la documentación comprensible para distintos equipos.
Genera códigos automáticamente desde tu especificación.
Mejora la colaboración y efectividad del trabajo en equipo.
Simplifica significativamente las validaciones de solicitudes y respuestas.
Aumenta considerablemente la adopción de servicios al proporcionar una documentación coherente y fácil de seguir.

Te invito a que revises el archivo de ejemplo proporcionado y compartas tus dudas o comentarios sobre cómo puedes aprovechar OpenAPI en tus próximos desarrollos.

Luis Rodolfo Altuve Cáceres

Hace un año

# Versión de OpenAPI
openapi: 3.0.0

# Información básica de la API
info:
  title: API de Ejemplo
  description:
    Esta es una API de ejemplo que muestra la estructura básica de un documento OpenAPI.
    Incluye ejemplos de endpoints, modelos de datos y autenticación.
  version: 1.0.0
  contact:
    name: Equipo de Soporte
    email: soporte@ejemplo.com

# Servidores disponibles
servers:
  - url: https://api.ejemplo.com/v1
    description: Servidor de producción
  - url: https://staging-api.ejemplo.com/v1
    description: Servidor de pruebas

# Componentes reutilizables
components:
	# Esquemas de datos
  schemas:
    Usuario:
      type: object
      properties:
        id:
          type: integer
          format: int64
        nombre:
          type: string
        email:
          type: string
          format: email
        activo:
          type: boolean
          default: true
      required:
        - nombre
        - email

	# Configuración de la seguridad
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

# Rutas de la API
paths:
  /usuarios:
  	# Método GET para obtener usuarios
    get:
      summary: Obtener lista de usuarios
      description: Retorna una lista paginada de usuarios
      security:
        - BearerAuth: []
      parameters:
        - name: pagina
          in: query
          description: Número de página
          required: false
          schema:
            type: integer
            default: 1
        - name: limite
          in: query
          description: Cantidad de elementos por página
          required: false
          schema:
            type: integer
            default: 10
      responses:
        '200':
          description: Lista de usuarios obtenida exitosamente
          content:
            application/json:
              schema:
              	type: array
              	items:
                	$ref: '#/components/schemas/Usuario'
        '401':
          description: No autorizado
        '500':
          description: Error en el servidor

		# Método POST para crear usuario
    post:
      summary: Crear nuevo usuarios    	
      description: Crea un nuevo usuario en el sistema
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Usuario'
      responses:
        '201':
          description: Usuario creado exitosamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Usuario'
        '400':
          description: Datos inválidos
        '401':
          description: No autorizado
        '500':
          description: Error en el servidor

  /usuarios/{id}:
  	# Parámetros de ruta
    parameters:
      - name: id
        in: path
        required: true
        description: ID del usuario
        schema:
          type: integer
          format: int64

    # Método GET para obtener un usuario específico
    get:
      summary: Obtener usuario por ID
      description: Retorna la información de un usuario específico
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Usuario encontrado
          content:
          	application/json:
          		schema:
          			$ref: '#/components/schemas/Usuario'
        '404':
          description: Usuario no encontrado
        '500':
          description: Error en el servidor
```# Versión de OpenAPI

openapi: 3.0.0



\# Información básica de la API

info:

&#x20; title: API de Ejemplo

&#x20; description:

&#x20;   Esta es una API de ejemplo que muestra la estructura básica de un documento OpenAPI.

&#x20;   Incluye ejemplos de endpoints, modelos de datos y autenticación.

&#x20; version: 1.0.0

&#x20; contact:

&#x20;   name: Equipo de Soporte

&#x20;   email: <soporte@ejemplo.com>



\# Servidores disponibles

servers:

&#x20; \- url: 

&#x20;   description: Servidor de producción

&#x20; \- url: 

&#x20;   description: Servidor de pruebas



\# Componentes reutilizables

components:

&#x9;\# Esquemas de datos

&#x20; schemas:

&#x20;   Usuario:

&#x20;     type: object

&#x20;     properties:

&#x20;       id:

&#x20;         type: integer

&#x20;         format: int64

&#x20;       nombre:

&#x20;         type: string

&#x20;       email:

&#x20;         type: string

&#x20;         format: email

&#x20;       activo:

&#x20;         type: boolean

&#x20;         default: true

&#x20;     required:

&#x20;       \- nombre

&#x20;       \- email



&#x9;\# Configuración de la seguridad

&#x20; securitySchemes:

&#x20;   BearerAuth:

&#x20;     type: http

&#x20;     scheme: bearer

&#x20;     bearerFormat: JWT



\# Rutas de la API

paths:

&#x20; /usuarios:

&#x20; 	\# Método GET para obtener usuarios

&#x20;   get:

&#x20;     summary: Obtener lista de usuarios

&#x20;     description: Retorna una lista paginada de usuarios

&#x20;     security:

&#x20;       \- BearerAuth: \[]

&#x20;     parameters:

&#x20;       \- name: pagina

&#x20;         in: query

&#x20;         description: Número de página

&#x20;         required: false

&#x20;         schema:

&#x20;           type: integer

&#x20;           default: 1

&#x20;       \- name: limite

&#x20;         in: query

&#x20;         description: Cantidad de elementos por página

&#x20;         required: false

&#x20;         schema:

&#x20;           type: integer

&#x20;           default: 10

&#x20;     responses:

&#x20;       '200':

&#x20;         description: Lista de usuarios obtenida exitosamente

&#x20;         content:

&#x20;           application/json:

&#x20;             schema:

&#x20;             	type: array

&#x20;             	items:

&#x20;               	$ref: '#/components/schemas/Usuario'

&#x20;       '401':

&#x20;         description: No autorizado

&#x20;       '500':

&#x20;         description: Error en el servidor



&#x9;	\# Método POST para crear usuario

&#x20;   post:

&#x20;     summary: Crear nuevo usuarios    &#x9;

&#x20;     description: Crea un nuevo usuario en el sistema

&#x20;     security:

&#x20;       \- BearerAuth: \[]

&#x20;     requestBody:

&#x20;       required: true

&#x20;       content:

&#x20;         application/json:

&#x20;           schema:

&#x20;             $ref: '#/components/schemas/Usuario'

&#x20;     responses:

&#x20;       '201':

&#x20;         description: Usuario creado exitosamente

&#x20;         content:

&#x20;           application/json:

&#x20;             schema:

&#x20;               $ref: '#/components/schemas/Usuario'

&#x20;       '400':

&#x20;         description: Datos inválidos

&#x20;       '401':

&#x20;         description: No autorizado

&#x20;       '500':

&#x20;         description: Error en el servidor



&#x20; /usuarios/{id}:

&#x20; 	\# Parámetros de ruta

&#x20;   parameters:

&#x20;     \- name: id

&#x20;       in: path

&#x20;       required: true

&#x20;       description: ID del usuario

&#x20;       schema:

&#x20;         type: integer

&#x20;         format: int64



&#x20;   \# Método GET para obtener un usuario específico

&#x20;   get:

&#x20;     summary: Obtener usuario por ID

&#x20;     description: Retorna la información de un usuario específico

&#x20;     security:

&#x20;       \- BearerAuth: \[]

&#x20;     responses:

&#x20;       '200':

&#x20;         description: Usuario encontrado

&#x20;         content:

&#x20;         	application/json:

&#x20;         		schema:

&#x20;         			$ref: '#/components/schemas/Usuario'

&#x20;       '404':

&#x20;         description: Usuario no encontrado

&#x20;       '500':

&#x20;         description: Error en el servidor

Luis Rodolfo Altuve Cáceres

Hace un año

El bloque inicial del comentario deja una referencia visual del archivo utilizado en esta clase. Luego por un error de interprestar el formato lo repite.

Comentarios (19)19 comentarios

Alfredo Olmedo

"Yet another markup language"

Gabriel Obregón

🗂 OpenAPI (antes Swagger)

📌 Definición

Especificación estándar para documentar APIs RESTful de forma clara y legible por humanos y máquinas, usando archivos YML. Permite comprender, desarrollar, consumir y mantener APIs de manera más eficiente.

🎯 Propósito

Hacer que las funcionalidades de una API sean fáciles de interpretar y utilizar. Incluye en el proyecto un archivo YML que permite:

📚 Documentación automática y actualizada
⚙️ Generación automática de código
✅ Validación de solicitudes y respuestas
🤝 Mejor colaboración entre equipos
🚀 Mayor adopción de APIs

🗂 Estructura de un archivo OpenAPI (YML)

1️⃣ Versión e información general

Versión de OpenAPI (ej. 3.1.1)
Título descriptivo
Descripción funcional
Datos de contacto

2️⃣ Servidores

Producción
Pruebas (staging)

3️⃣ Definición de rutas (paths)

Métodos (GET, POST, etc.) Parámetros, descripciones y requisitos
Respuestas HTTP con esquemas y tipos de datos

4️⃣ Componentes reutilizables

Esquemas compartidos (ej. usuario: ID, nombre, email)
Configuración de seguridad

⭐ Ventajas clave

Documentación clara para todos los equipos
Código generado automáticamente
Colaboración más eficiente
Validaciones simplificadas
Mayor adopción gracias a documentación coherente

💡 Tip rápido: un buen archivo OpenAPI no solo describe la API, sino que también sirve como base para generar clientes, pruebas y documentación interactiva.

Daniel Guerrero

Hola, teniendo en mente lo variado, la múltiplicidad de requisitos me pregunte si existirian templates o preformateados y encontré que existen variedad de recursos y herramientas que presentan soporte preformateado, pinta bien APIfirst con OpenApi, no?

Carlos Herrera Wiese

pense que era un curso para aprender de APIS, pero parece que es mas avanzado.

Tetsu Osnaya

Yo igual, venia pensando que me iba a explicar como usar APIs, y no. Es para crear tu API.

Vanessa Agudelo Marín

Hace 4 meses

No hay archivo de ejemplo publicado :(

Jorge Arias Argüelles

En los 90s y principios de los 2000:

XML era el estándar para representar datos estructurados (ej. configuración de proyectos Java, SOAP, etc.).
Problemas de XML:
- Muy verboso (muchas etiquetas repetitivas).
- Poco legible para humanos.
- Difícil de mantener en configuraciones grandes.

YAML nació como una forma de escribir datos con sangrías y guiones (más natural, como pseudocódigo o listas en un cuaderno).

XML (antes de YAML):

<servidor>
  <puerto>8080</puerto>
  <entorno>producción</entorno>
  <usuarios>
    <usuario>admin</usuario>
    <usuario>invitado</usuario>
  </usuarios>
</servidor>

YAML (mucho más legible):

servidor:
  puerto: 8080
  entorno: producción
  usuarios:
    - admin
    - invitado

Eduardo Esteban Álvarez Castañeda

si no mal recuerdo, existen herramientas que permiten escribir la especificación de manera automática, escribiendo comentarios sobre el controllador o el router los métodos y en los modelos/interfaces los schemas

David Rangel

Hace 8 meses

Fast Api que usa Python documenta automáticamente tu aplicación.

Irving Juárez

Al final es seguir un framework de documentación para nuestras APIs

Sergio Brandon De Lucio Chavero

Como idea: Este openAPI.yaml puede ser muy util adjuntarlo al agente de codigo que estemos usando: Cursor, Windsurf, Claude Code, etc. ya que asi comprendera todos los endpoints y su estructura, sin embargo puede llegar a ser un poco grande, por lo que solo se tiene que consultar cuando sea necesario ya que puede llegar a desviar la atencion del LLM.

Jefred Bedoya

Hace 4 meses•editado

Especificación OpenAPI para APIs RESTful

Resumen general

OpenAPI es un estándar para definir interfaces de APIs RESTful, permitiendo que tanto humanos como máquinas comprendan sus capacidades. Utiliza archivos YAML para describir endpoints, esquemas de datos, métodos y seguridad, facilitando la colaboración, automatización y consumo de servicios.

Conceptos clave

Especificación: Documento estructurado que actúa como contrato de la API.
YAML: Lenguaje de serialización legible utilizado para definir la especificación.
Endpoints (Paths): Rutas de acceso a los recursos de la API.
Esquemas (Components): Modelos de datos reutilizables que definen la estructura de los objetos.

Desarrollo

La estructura del archivo openapi.yaml se organiza en bloques jerárquicos:

Info: Metadatos (título, versión, contacto).
Servers: URLs de despliegue (producción, staging).
Components: Definición de esquemas y reglas de seguridad.
Paths: Configuración de métodos (GET, POST, etc.), parámetros, cuerpos de solicitud y respuestas HTTP.

Herramientas/Metodologías

OpenAPI 3.1.1: Versión estándar actual.
Documentación como código: Integrar la definición directamente en el repositorio del proyecto.

Buenas prácticas

Reutilización: Definir esquemas en components para evitar redundancia.
Detalle: Especificar estados HTTP (200, 400, 500) y requisitos de seguridad en cada endpoint.
Legibilidad: Mantener una indentación clara en el YAML para facilitar el mantenimiento.

Conclusiones

Implementar OpenAPI es esencial para la escalabilidad. Permite la generación automática de documentación, validación de tráfico y la creación de código cliente/servidor a partir de la especificación, eliminando ambigüedades entre equipos.

Daniel Acosta Bermúdez

Hace 5 meses

Bonita analogía:

API = edificio Endpoint = puerta específica Schema = forma del paquete que puede entrar por la puerta. OpenAPI = plano/documentación del edificio Swagger UI = mapa visual interactivo RESTful = reglas de diseño del edificio y sus puertas

Andres Felipe Garcia Ospina

Hace 6 meses

cuales son las alternativas a opeapi, esto es una "Arquitectura"

Hola, Andres Felipe. Es una excelente pregunta. Aunque OpenAPI es el estándar de la industria para APIs RESTful, existen alternativas que abordan la documentación y el diseño desde enfoques distintos:

RAML (RESTful API Modeling Language): Muy similar a OpenAPI, se basa en YAML y se enfoca en la reutilización de código y la modularidad. Es muy popular en entornos empresariales.
API Blueprint: Utiliza una sintaxis basada en Markdown, lo que lo hace extremadamente legible para humanos. Es ideal si priorizas la documentación narrativa sobre la configuración técnica.
GraphQL (Schema Definition Language): Si tu arquitectura no es REST, GraphQL incluye su propia especificación de esquema integrada, lo que elimina la necesidad de un archivo de documentación externo.

Cada una cumple el rol de "contrato" entre cliente y servidor. Para profundizar en cómo esto se integra en tu flujo de trabajo, te recomiendo revisar: ¿Qué es API First?.

Alex Sandoval

Buena introducción. APIs firt nos ayuda agilizar las especificaciones de contrato con los diferentes sistemas externos.

Cesar Bautista Mejia

En .NET Web API ya viene esto nativamente dentro de los templates, almenos antes del .NET 9, ahora lo tienes que "Activar".

Dice Fredy que estamos muy obligados a seguir una estructura que nos de confianza como lo son las {}, pero al tener algo tan flexible carece de control donde se basa en aprender la "Sintaxis" donde nisiquiera podemos escribir correctamente sin utilizar el autocorrector.

Antonio Obregón

En el bloque components tambien puedes agregar elementos como:

parameters
requestBodies
responses

De tal forma que tus path queden limpios y que se promueva la reutilización de los schemas.

Importante!!!

Los schemas deben ser modelos de negocio o entidades, recordemos que la filosofía REST promueve la representación de estados sobre entidades.

Una forma rápida de verificar que el contrato tiene buena estructura es observar en el swagger UI que solo existen modelos o propiedades que representan modelos de negocio

Marcos Vázquez González

La clase se centró en la especificación OpenAPI, antes conocida como Swagger, que permite documentar APIs RESTful de manera estructurada y legible. Los puntos clave incluyen:

Estructura del archivo: Contiene versiones, información general, servidores, paths, y componentes reutilizables.
Documentación automática: Facilita la comprensión para desarrolladores y equipos.
Validación y generación de código: Mejora la colaboración y la implementación de APIs.
Capacidades de seguridad y manejo de errores: Define respuestas y comportamientos en distintas situaciones.

Estos elementos son cruciales para diseñar APIs robustas y escalables.

Gracias chatgpt, buen resumen

Francisco August

¡Excelente resumen! OpenAPI es la clave para acabar con el caos en la documentación de APIs y acelerar el desarrollo. 🚀 Su enfoque estandarizado es un verdadero salvavidas para la colaboración entre equipos. 📖✨

¿Todavía documentas a mano?

Cristian Franco

Pinta bastante bien este curso, muy interesante.

Introducción y Fundamentos de API First

API First con OpenAPI antes de programar

Especificación OpenAPI para documentar APIs RESTful

Configuración inicial de proyecto ExpressJS con especificación OpenAPI

Construcción de API con Express y documentación Swagger

Herramientas y Validación de APIs

Validación automática con Express OpenAPI Validator

Validación automática con OpenAPI en Express

Múltiples respuestas HTTP en OpenAPI

Cómo la IA genera endpoints desde OpenAPI

Esquemas reutilizables de productos en OpenAPI

Endpoints de productos con esquemas reutilizables

API First con IA: construye CRUD sin codificar

Versionado, Prototipado y Documentación

Versionado de APIs con OpenAPI

Cómo crear un mock server con Prism CLI

Organización y mejora de documentación OpenAPI

Agregar ejemplos reales en especificaciones OpenAPI

Validación y Pruebas de Contratos

Errores en OpenAPI que Swagger Editor detecta

Importación de OpenAPI a Postman para automatizar pruebas

Pruebas de API con Newman en tu pipeline

Seguridad

Proteger endpoints con JWT en OpenAPI

Especificación OpenAPI para documentar APIs RESTful

Progreso del curso

Introducción y Fundamentos de API First

Herramientas y Validación de APIs

Versionado, Prototipado y Documentación

Validación y Pruebas de Contratos

Seguridad

Recursos

Recursos