¿Cómo puedo crear un documento OpenAPI desde cero?

¿Cómo puedo crear un documento OpenAPI desde cero? #

Crear un documento OpenAPI desde cero es una habilidad fundamental para desarrollar y documentar API. La especificación OpenAPI (OAS) es un estándar para definir API RESTful que permite tanto a personas como a máquinas comprender las capacidades de un servicio web sin acceder directamente a su implementación. Este artículo te guiará a través de los pasos para crear un documento OpenAPI desde cero, y repasará las herramientas, las buenas prácticas y los flujos de trabajo que pueden ayudarte.

Comprender la especificación OpenAPI #

Antes de entrar en el proceso de creación, es esencial entender qué es un documento OpenAPI. Un documento OpenAPI describe los endpoints, los modelos de solicitud y respuesta, la autenticación y otros aspectos de una API. Normalmente, el documento se escribe en formato YAML o JSON.

Para consultar la especificación completa, puedes acudir a la especificación OpenAPI que proporciona Swagger.

Guía paso a paso para crear un documento OpenAPI #

1. Configura tu entorno #

En primer lugar, asegúrate de contar con un conjunto de herramientas adecuado para editar y probar tu documento OpenAPI. Algunas herramientas populares son:

Swagger Editor: una potente herramienta en línea que ofrece una interfaz gráfica para crear y editar documentos OpenAPI. Visita Swagger Editor.
VS Code con una extensión de OpenAPI: si prefieres un editor de código de escritorio, Visual Studio Code con la extensión Swagger Viewer es una opción sólida.
Postman: conocido por las pruebas de API, Postman también ofrece funciones para generar documentación OpenAPI.

2. Define la estructura básica #

Empieza definiendo la estructura básica de tu documento OpenAPI. A continuación se muestra el formato YAML de la cabecera de un documento OpenAPI:

openapi: 3.0.0
info:
  title: Sample API
  description: A sample API to illustrate how to create an OpenAPI document
  version: 1.0.0
servers:
  - url: https://api.example.com/v1

En esta estructura:

openapi: especifica la versión de OpenAPI.
info: contiene metadatos sobre la API, como el título, la descripción y la versión.
servers: enumera los servidores donde está alojada tu API.

3. Documenta las rutas de la API #

A continuación, define las rutas (endpoints) que expone tu API. Cada ruta debe incluir los métodos HTTP admitidos, los parámetros, los cuerpos de solicitud y las respuestas. Este es un ejemplo de un endpoint sencillo con GET y POST:

paths:
  /users:
    get:
      summary: Retrieve a list of users
      responses:
        '200':
          description: A JSON array of user names
          content:
            application/json:
              schema:
                type: array
                items: 
                  type: string

    post:
      summary: Create a new user
      requestBody:
        description: User object that needs to be added
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  type: string
                email:
                  type: string
      responses:
        '201':
          description: User created successfully

En este ejemplo:

Cada endpoint (/users) tiene métodos (get, post) con descripciones, cuerpos de solicitud y esquemas de respuesta.
El campo responses describe las respuestas, incluidos los códigos de estado (200 para éxito), el tipo de contenido (application/json) y la estructura de los datos de la respuesta (schema).

4. Añade parámetros #

Los endpoints de una API suelen requerir parámetros, como cadenas de consulta, encabezados o variables de ruta. A continuación se muestra un ejemplo de un endpoint con un parámetro de ruta:

  /users/{userId}:
    get:
      summary: Get a user by ID
      parameters:
        - name: userId
          in: path
          required: true
          description: Numeric ID of the user to retrieve
          schema:
            type: integer
      responses:
        '200':
          description: A single user
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  username:
                    type: string
                  email:
                    type: string

En este ejemplo, la lista parameters incluye una variable de ruta userId:

name: el nombre del parámetro.
in: especifica dónde se encuentra el parámetro (path, query, header, etc.).
schema: define el tipo del parámetro.

5. Define componentes #

Los parámetros, cuerpos de solicitud o esquemas de respuesta comunes pueden reutilizarse en todas las definiciones de tu API si los defines en la sección components. Esto reduce la redundancia y simplifica el mantenimiento:

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        username:
          type: string
        email:
          type: string
  parameters:
    UserId:
      name: userId
      in: path
      required: true
      schema:
        type: integer
  requestBodies:
    User:
      description: User object that needs to be added
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/User'

Después, puedes referenciar estos componentes dentro de las definiciones de tus rutas:

  /users:
    post:
      summary: Create a new user
      requestBody:
        $ref: '#/components/requestBodies/User'
      responses:
        '201':
          description: User created successfully

6. Añade esquemas de seguridad #

La seguridad es una parte fundamental del desarrollo de API. OpenAPI te permite definir esquemas de seguridad y aplicarlos de forma global o a operaciones específicas. Por ejemplo, para definir un esquema de seguridad basado en clave de API:

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
security:
  - ApiKeyAuth: []

En este ejemplo:

securitySchemes: define los mecanismos de seguridad disponibles.
security: aplica el esquema ApiKeyAuth de forma global.

7. Genera documentación y SDK #

Una de las ventajas de OpenAPI es la posibilidad de generar automáticamente documentación y SDK en varios lenguajes de programación. Herramientas como Swagger Codegen y OpenAPI Generator simplifican este proceso.

8. Valida y prueba tu documento OpenAPI #

La validación garantiza que tu documento OpenAPI cumpla la especificación y no contenga errores. Herramientas como:

Swagger Editor ofrece validación en tiempo real.
Swagger CLI permite validar desde la línea de comandos.

Para las pruebas, herramientas como Postman permiten importar tu documento OpenAPI para crear y componer pruebas automatizadas.

9. Integración y despliegue continuos (CI/CD) #

Incorpora tu documento OpenAPI a tus pipelines de CI/CD para asegurarte de que tu API se mantenga coherente y bien documentada a lo largo de los cambios. Herramientas como GitHub Actions, CircleCI y Jenkins pueden configurarse para validar y probar tu documento en cada commit.

Conclusión #

Crear un documento OpenAPI desde cero implica varios pasos estructurados, desde configurar tu entorno, definir endpoints y documentar parámetros y esquemas, hasta implementar la seguridad y probar tu documentación. Utilizar herramientas como Swagger Editor, Postman y pipelines automatizados de CI/CD puede facilitar el proceso de creación y garantizar que tu API sea robusta, esté bien documentada y lista para que los desarrolladores la consuman.

Para obtener más lecturas y recursos, visita la OpenAPI Initiative, Swagger.io y el Postman Learning Center.

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