OpenAPI y Swagger para documentación de APIs

Vale la pena dedicar tiempo a conocer Swagger, porque como desarrollador de aplicaciones inevitablemente trabajarás con APIs. Swagger se convertirá en tu mejor aliado cuando sepas cómo usarlo. No es complicado, incluso si necesitas una API Key de antemano, sigue siendo accesible. Swagger, al igual que Postman, te ofrece una interfaz de prueba lista para usar. Seleccionas el endpoint y puedes empezar a hacer pruebas inmediatamente.

OpenAPI es el estándar para describir APIs REST de forma legible por máquinas y forma la base de documentación interactiva, servidores mock y generación de código.

Descripción compacta

OpenAPI es un formato de especificación para APIs REST que describe endpoints, métodos, parámetros, esquemas de request y response, códigos de estado, formatos de error y mecanismos de seguridad. Típicamente se escribe en YAML o JSON y funciona como única fuente confiable para desarrolladores, testers, generadores de clientes y documentación. Swagger es históricamente un nombre y hoy designa un conjunto de herramientas alrededor de OpenAPI, incluyendo Swagger UI, Swagger Editor y Swagger Codegen. OpenAPI posibilita API First Design, pruebas automatizadas y creación de documentaciones interactivas. Una especificación OpenAPI de calidad es completa, consistente y enriquecida con ejemplos, de modo que los usuarios puedan entender la API y experimentar con ella sin necesidad de leer el código.

Componentes importantes

Versión de OpenAPI

OpenAPI se ofrece en las versiones 2.0, 3.0 y 3.1. Las versiones 3.0 y 3.1 brindan más flexibilidad que 2.0, especialmente en definiciones de request y response, links y callbacks. En proyectos nuevos deberías usar una versión actual y mantener las antiguas solo por compatibilidad.

Info y metadatos

El bloque info contiene información básica como título, versión, descripción e información de contacto. Estos metadatos son cruciales para identificar la API y la documentación automatizada.

URLs de servidor

Las URLs de servidor definen bajo qué direcciones es accesible la API. Puedes especificar múltiples entornos como development, staging y production. Las variables permiten hacer dinámicas partes de la URL.

Paths y operaciones

Los paths describen los endpoints de la API. Cada path puede contener múltiples operaciones, por ejemplo get, post, put, delete, patch. Cada operación incluye summary, description, tags, parámetros, request body y responses.

Components y esquemas

Components contienen definiciones reutilizables como esquemas, parámetros, responses, headers y security schemas. Los esquemas definen la estructura de datos de requests y responses con tipos, campos obligatorios, formatos y ejemplos.

Parámetros

Los parámetros se pueden transmitir en path, query, header o cookie. Se definen con nombre, tipo, formato, requerido y descripción. Los ejemplos y reglas de validación como minLength o pattern mejoran la calidad.

Request Body

El request body describe los datos que el cliente debe enviar en POST, PUT o PATCH. Típicamente referencia un esquema y puede soportar múltiples content-types como application/json o application/xml.

Responses

Las responses definen las posibles respuestas de una operación. Cada código de estado se describe con descripción, content-type y esquema. También las respuestas de error como 400 o 404 deben documentarse completamente.

Security Schemas

Los security schemas describen cómo está protegida la API. Los procedimientos típicos son HTTP Basic, Bearer Token, OAuth2 y API Keys. Los esquemas se definen en Components y se referencian en las operaciones.

Swagger UI y Redoc

Swagger UI y Redoc son herramientas que generan documentación HTML interactiva a partir de una especificación OpenAPI. Swagger UI permite probar directamente los endpoints en el navegador; Redoc enfatiza la presentación atractiva y legibilidad.

Generación de código

OpenAPI Generator produce código de cliente y servidor a partir de la especificación. Acelera el desarrollo, reduce errores y garantiza que cliente y servidor se basen en el mismo contrato. Se soportan muchos lenguajes de programación y frameworks.

Ejemplo práctico

Una tienda define su API de pedidos con OpenAPI:

openapi: 3.0.3
info:
  title: Shop API
  version: 1.0.0
  description: API para la gestión de pedidos

servers:
  - url: https://api.shop.example.com/v1

paths:
  /orders:
    post:
      summary: Crear pedido
      tags:
        - Orders
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderRequest'
      responses:
        '201':
          description: Pedido creado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '400':
          description: Entrada inválida

components:
  schemas:
    OrderRequest:
      type: object
      required:
        - customerId
        - items
      properties:
        customerId:
          type: integer
          example: 123
        items:
          type: array
          items:
            $ref: '#/components/schemas/OrderItem'
    OrderItem:
      type: object
      required:
        - productId
        - quantity
      properties:
        productId:
          type: integer
          example: 42
        quantity:
          type: integer
          minimum: 1
          example: 2
    Order:
      type: object
      properties:
        orderId:
          type: integer
          example: 98765
        status:
          type: string
          example: created

A partir de esta especificación, Swagger UI puede generar documentación interactiva, OpenAPI Generator puede crear clientes para JavaScript, Python o Java, y los testers pueden ejecutar validaciones de esquema.

FAQ: OpenAPI y Swagger

1. ¿Qué es OpenAPI?

OpenAPI es un formato legible por máquinas para describir APIs REST. Define endpoints, métodos, parámetros, esquemas, códigos de estado y mecanismos de seguridad.

2. ¿Cuál es la diferencia entre OpenAPI y Swagger?

OpenAPI es la especificación. Swagger es un nombre de marca para herramientas como Swagger UI, Swagger Editor y Swagger Codegen que utilizan documentos OpenAPI. Anteriormente, la especificación misma se llamaba Swagger.

3. ¿En qué formato se escribe OpenAPI?

OpenAPI se escribe en YAML o JSON. YAML es más común por su mejor legibilidad; JSON se usa frecuentemente para procesamiento automatizado.

4. ¿Qué es Swagger UI?

Swagger UI es una herramienta que genera documentación HTML interactiva a partir de una especificación OpenAPI. Los usuarios pueden probar endpoints directamente en el navegador.

5. ¿Qué es Redoc?

Redoc es una herramienta de código abierto que genera documentaciones atractivas y bien legibles a partir de especificaciones OpenAPI. Es particularmente adecuada para documentación de usuarios finales.

6. ¿Qué son Components en OpenAPI?

Components contienen definiciones reutilizables como esquemas, parámetros, responses y security schemas. Permiten una especificación consistente y mantenible.

7. ¿Qué es la generación de código con OpenAPI?

La generación de código produce código de cliente o servidor a partir de una especificación OpenAPI. Acelera el desarrollo y garantiza que cliente y servidor se basen en el mismo contrato.

8. ¿Qué es un esquema en OpenAPI?

Un esquema en OpenAPI define la estructura de datos. Establece tipos, campos obligatorios, formatos, ejemplos y reglas de validación para request bodies y responses.

9. ¿Qué son los Security Schemas?

Los security schemas describen cómo está protegida la API. Los procedimientos típicos son Bearer Token, API Keys, HTTP Basic y OAuth2. Se definen en Components y se referencian en operaciones.

10. ¿Qué es una única fuente confiable?

Una única fuente confiable es una fuente única y autoritaria de información. OpenAPI es la única fuente confiable para la API, de la que se genera documentación, tests y código.

11. ¿Qué es API First Design?

API First Design significa que la especificación de API se crea antes de la implementación. OpenAPI es la herramienta central para este enfoque.

12. ¿Qué es un servidor mock de OpenAPI?

Un servidor mock simula una API basándose en la especificación OpenAPI. Proporciona respuestas predefinidas y permite desarrollar clientes antes de que la API real esté lista.

13. ¿Cuál es la ventaja de OpenAPI para testers?

Los testers pueden usar OpenAPI para crear validaciones de esquema, contract tests y pruebas automatizadas. La especificación sirve como referencia para requests y responses esperados.

14. ¿Qué es OpenAPI Linting?

OpenAPI Linting verifica la especificación para detectar violaciones de reglas, inconsistencias y componentes faltantes. Herramientas como Spectral ayudan a garantizar especificaciones de alta calidad.

15. ¿Cuáles son las mejores prácticas para especificaciones OpenAPI?

Las mejores prácticas incluyen endpoints y responses completos, components reutilizables, ejemplos significativos, descripciones claras, security schemas correctos, versionamiento y mantenimiento regular de la especificación.

Continúa en el camino de aprendizaje de API

El siguiente artículo en el camino de aprendizaje de API cubre mejores prácticas en documentación de API, donde descubrirás cómo escribir documentación que los desarrolladores realmente entienden y utilizan.

Referencias

Recomendaciones de libros para desarrollo de API

Si quieres profundizar en OpenAPI, documentación de API y diseño de API, te sugerimos los siguientes libros:

Keine Bücher für Kategorie "api-development" gefunden.

Täglicher Artikel