Escribir el primer documento Swagger

Swagger (OpenAPI) es una especificación y un conjunto de herramientas para describir, generar y visualizar servicios web RESTful.

A continuación, te explicaré en detalle cómo escribir tu primer documento Swagger desde cero.

Los documentos Swagger utilizan principalmente formatos YAML o JSON y definen varios aspectos de la API, incluyendo:

Información básica de la API (título, versión, etc.)
Rutas y operaciones disponibles
Parámetros de entrada y respuestas de salida
Métodos de autenticación
Definición de modelos de datos

Pasos de creación

1. Crear la estructura básica de archivos

Primero, crea un archivo llamadoswagger.yamloswagger.json. Este tutorial utiliza el formato YAML como ejemplo, porque es más fácil de leer y escribir.

Ejemplo
openapi: 3.0.0
info:
title:Mi primera API
description:Este es un documento de ejemplo simple de API
version: 1.0.0
contact:
name:Equipo de soporte de API
email: support@example.com
url: https://www.example.com/support
servers:
- url: https://api.example.com/v1
description:Entorno de producción
- url: https://dev-api.example.com/v1
description:Entorno de desarrollo

2. Agregar información básica del documento

Ejemplo
openapi: 3.0.0
info:
title:Mi primera API
description:Este es un documento de ejemplo simple de API
version: 1.0.0
contact:
name:Equipo de soporte de API
email: support@example.com
url: https://www.example.com/support
servers:
- url: https://api.example.com/v1
description:Entorno de producción
- url: https://dev-api.example.com/v1
description:Entorno de desarrollo

3. Definir rutas y operaciones

Las rutas definen los endpoints a los que se puede acceder en la API, y las operaciones definen los métodos HTTP (GET, POST, PUT, DELETE, etc.) que se pueden ejecutar en esos endpoints.

Ejemplo
paths:
/users:
get:
summary:Obtener lista de todos los usuarios
description:Devuelve la información de todos los usuarios del sistema
operationId: getUsers
parameters:
- name: limit
in: query
description:Número máximo de resultados a devolver
required: false
schema:
type: integer
format: int32
minimum: 1
maximum: 100
default: 20
responses:
'200':
description:Lista de usuarios obtenida con éxito
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/User'
'400':
description:Solicitud no válida
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
post:
summary:Crear nuevo usuario
description:Crea un nuevo usuario en el sistema
operationId: createUser
requestBody:
description:Información del usuario
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/NewUser'
responses:
'201':
description:Usuario creado con éxito
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'400':
description:Solicitud no válida
content:
application/json:
schema:
$ref: '#/components/schemas/Error'

4. Definir componentes y modelos

EncomponentsLa sección define modelos reutilizables:

Ejemplo
components:
schemas:
User:
type: object
properties:
id:
type: integer
format: int64
description:Identificador único del usuario
username:
type: string
description:Nombre de usuario
email:
type: string
format: email
description:Correo electrónico del usuario
status:
type: string
enum: [active, inactive, banned]
description:Estado del usuario
createdAt:
type: string
format: date-time
description:Fecha de creación
required:
- id
- username
- email
- status

NewUser:
type: object
properties:
username:
type: string
description:Nombre de usuario
email:
type: string
format: email
description:Correo electrónico del usuario
password:
type: string
format: password
description:Contraseña del usuario
minLength: 8
required:
- username
- email
- password

Error:
type: object
properties:
code:
type: integer
format: int32
message:
type: string
required:
- code
- message

5. Agregar definiciones de seguridad

Define los requisitos de seguridad de la API:

Ejemplo
security:
- bearerAuth: []

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

6. Ejemplo de documento completo

Combina todas las secciones anteriores y tendrás un documento Swagger completo.

Ejemplo

openapi: 3.0.0
info:
title:Mi primera API
description:Este es un documento de ejemplo simple de API
version: 1.0.0
contact:
name:Equipo de soporte de API
email: support@example.com
url: https://www.example.com/support
servers:
- url: https://api.example.com/v1
description:Entorno de producción
- url: https://dev-api.example.com/v1
description:Entorno de desarrollo

paths:
/users:
get:
summary:Obtener lista de todos los usuarios
description:Devuelve la información de todos los usuarios del sistema
operationId: getUsers
parameters:
- name: limit
in: query
description:Número máximo de resultados a devolver
required: false
schema:
type: integer
format: int32
minimum: 1
maximum: 100
default: 20
responses:
'200':
description:Lista de usuarios obtenida con éxito
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/User'
'400':
description:Solicitud no válida
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
post:
summary:Crear nuevo usuario
description:Crea un nuevo usuario en el sistema
operationId: createUser
requestBody:
description:Información del usuario
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/NewUser'
responses:
'201':
description:Usuario creado con éxito
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'400':
description:Solicitud no válida
content:
application/json:
schema:
$ref: '#/components/schemas/Error'

components:
schemas:
User:
type: object
properties:
id:
type: integer
format: int64
description:Identificador único del usuario
username:
type: string
description:Nombre de usuario
email:
type: string
format: email
description:Correo electrónico del usuario
status:
type: string
enum: [active, inactive, banned]
description:Estado del usuario
createdAt:
type: string
format: date-time
description:Fecha de creación
required:
- id
- username
- email
- status

NewUser:
type: object
properties:
username:
type: string
description:Nombre de usuario
email:
type: string
format: email
description:Correo electrónico del usuario
password:
type: string
format: password
description:Contraseña del usuario
minLength: 8
required:
- username
- email
- password

Error:
type: object
properties:
code:
type: integer
format: int32
message:
type: string
required:
- code
- message

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

security:
- bearerAuth: []

7. Usar herramientas de Swagger

Hay varias formas de visualizar y probar tu documento Swagger:

Swagger UI: una página de documentación interactiva
Swagger Editor: editor en línea que permite previsualizar el documento en tiempo real
Swagger Codegen: herramienta para generar código de cliente

8. Probar tu documento en línea

Puedes usarSwagger Editorpara probar tu documento en línea. Simplemente copia y pega tu YAML o JSON en el editor, y el panel derecho mostrará la documentación visual de la API.

9. Mejores prácticas

Utiliza ID de operación significativos
Proporciona descripciones detalladas para cada endpoint
Asegúrate de que todos los parámetros tengan descripción
Documenta todos los códigos de estado de respuesta posibles
Utiliza referencias a modelos para reducir la duplicación
Mantén el documento actualizado
Agrega ejemplos de solicitudes y respuestas para cada endpoint

10. Ubicaciones comunes de parámetros

Swagger define varias ubicaciones de parámetros:

path: parámetros en la ruta de la URL, como/users/{id}
query: parámetros de consulta en la URL, como/users?limit=10
header: parámetros de cabecera HTTP
cookie: parámetros de cookie
body: parámetros del cuerpo de la solicitud (en OpenAPI 3.0 se usa requestBody en su lugar)

11. Ampliar tu documento

A medida que la API evoluciona, continúa ampliando tu documento Swagger:

Agregar más endpoints
Definir modelos adicionales
Añadir descripciones más detalladas
Agregar ejemplos de solicitudes y respuestas

12. Integración en el desarrollo real

En el desarrollo real, puedes:

Integrar Swagger en tu código
Usar herramientas de generación automática
Generar documentación a partir de comentarios del código
Incrustar Swagger UI en tu aplicación

Otras extensiones