Ejemplo de documento Swagger
A continuación se muestra un ejemplo completo de documento Swagger, que es una especificación detallada de una API de sistema de gestión de usuarios.
Este documento describe una API de sistema de gestión de usuarios, que incluye información básica del usuario, servicio de autenticación, modelo de datos, etc.
Esta API sigue el estilo RESTful y utiliza el formato JSON para el intercambio de datos.
Podemos usar Swagger Editor para probar tu documento en línea. La dirección en línea es:https://editor.swagger.io/Solo tienes que copiar y pegar tu YAML o JSON en el editor, y el panel derecho mostrará el documento de API visualizado.

Ejemplo
info:
title:Mi primera API
description: |
Este es un documento de ejemplo de API simple que muestra las funciones básicas del sistema de gestión de usuarios.
Incluye operaciones de consulta, creación, actualización y eliminación de usuarios.
version: 1.0.0
contact:
name:Equipo de soporte de API
email: support@example.com
url: https://www.example.com/support
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://api.example.com/v1
description:Entorno de producción
- url: https://staging-api.example.com/v1
description:Entorno de preproducción
- url: https://dev-api.example.com/v1
description:Entorno de desarrollo
tags:
- name:Usuario
description:Operaciones relacionadas con la gestión de usuarios
- name:Autenticación
description:Operaciones relacionadas con la autenticación
paths:
/users:
get:
tags:
-Usuario
summary:Obtener lista de todos los usuarios
description:Devuelve la información de todos los usuarios del sistema, con soporte para paginación y filtrado.
operationId: getUsers
parameters:
- name: limit
in: query
description:Número máximo de resultados devueltos
required: false
schema:
type: integer
format: int32
minimum: 1
maximum: 100
default: 20
- name: offset
in: query
description:Desplazamiento de paginación
required: false
schema:
type: integer
format: int32
minimum: 0
default: 0
- name: status
in: query
description:Filtrar por estado de usuario
required: false
schema:
type: string
enum: [active, inactive, banned]
responses:
'200':
description:Lista de usuarios obtenida exitosamente
content:
application/json:
schema:
type: object
properties:
total:
type: integer
description:Número total de usuarios
users:
type: array
items:
$ref: '#/components/schemas/User'
example:
total: 2
users:
- id: 1
username: "john_doe"
email: "john@example.com"
status: "active"
createdAt: "2023-05-01T12:00:00Z"
- id: 2
username: "jane_smith"
email: "jane@example.com"
status: "active"
createdAt: "2023-05-02T14:30:00Z"
'400':
description:Solicitud no válida
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
$ref: '#/components/responses/UnauthorizedError'
security:
- bearerAuth: []
post:
tags:
-Usuario
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'
example:
username: "new_user"
email: "new_user@example.com"
password: "securePassword123"
responses:
'201':
description:Usuario creado exitosamente
content:
application/json:
schema:
$ref: '#/components/schemas/User'
example:
id: 3
username: "new_user"
email: "new_user@example.com"
status: "active"
createdAt: "2023-05-10T09:15:00Z"
'400':
description:Solicitud no válida
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 400
message: "Formato de correo electrónico incorrecto"
'409':
description:Conflicto de recursos
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 409
message: "El nombre de usuario ya existe"
'401':
$ref: '#/components/responses/UnauthorizedError'
security:
- bearerAuth: []
/users/{userId}:
parameters:
- name: userId
in: path
description:ID de usuario
required: true
schema:
type: integer
format: int64
get:
tags:
-Usuario
summary:Obtener usuario específico
description:Obtiene la información detallada de un usuario específico según su ID
operationId: getUserById
responses:
'200':
description:Información del usuario obtenida exitosamente
content:
application/json:
schema:
$ref: '#/components/schemas/UserDetail'
example:
id: 1
username: "john_doe"
email: "john@example.com"
firstName: "John"
lastName: "Doe"
phone: "+1234567890"
status: "active"
createdAt: "2023-05-01T12:00:00Z"
lastLogin: "2023-05-10T08:30:00Z"
'404':
description:El usuario no existe
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 404
message: "El usuario no existe"
'401':
$ref: '#/components/responses/UnauthorizedError'
security:
- bearerAuth: []
put:
tags:
-Usuario
summary:Actualizar información del usuario
description:Actualiza la información de un usuario específico
operationId: updateUser
requestBody:
description:Información del usuario a actualizar
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateUser'
example:
firstName: "Jonathan"
lastName: "Doe"
phone: "+1987654321"
responses:
'200':
description:Información del usuario actualizada exitosamente
content:
application/json:
schema:
$ref: '#/components/schemas/UserDetail'
'400':
description:Solicitud no válida
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description:El usuario no existe
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
$ref: '#/components/responses/UnauthorizedError'
security:
- bearerAuth: []
delete:
tags:
-Usuario
summary:Eliminar usuario
description:Elimina un usuario específico del sistema
operationId: deleteUser
responses:
'204':
description:Usuario eliminado exitosamente
'404':
description:El usuario no existe
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
$ref: '#/components/responses/UnauthorizedError'
security:
- bearerAuth: []
/auth/login:
post:
tags:
-Autenticación
summary:Inicio de sesión de usuario
description:El usuario inicia sesión y obtiene un token de acceso
operationId: login
requestBody:
description:Credenciales de inicio de sesión
required: true
content:
application/json:
schema:
type: object
properties:
username:
type: string
description:Nombre de usuario
password:
type: string
format: password
description:Contraseña
required:
- username
- password
example:
username: "john_doe"
password: "password123"
responses:
'200':
description:Inicio de sesión exitoso
content:
application/json:
schema:
type: object
properties:
accessToken:
type: string
description:Token de acceso JWT
tokenType:
type: string
description:Tipo de token
expiresIn:
type: integer
description:Tiempo de expiración del token (segundos)
example:
accessToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
tokenType: "Bearer"
expiresIn: 3600
'401':
description:Inicio de sesión fallido
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 401
message: "Nombre de usuario o contraseña incorrectos"
/auth/register:
post:
tags:
-Autenticación
summary:Registro de usuario
description:Registra un nuevo usuario y obtiene un token de acceso
operationId: register
requestBody:
description:Información de registro
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/NewUser'
responses:
'201':
description:Registro exitoso
content:
application/json:
schema:
type: object
properties:
user:
$ref: '#/components/schemas/User'
accessToken:
type: string
description:Token de acceso JWT
example:
user:
id: 3
username: "new_user"
email: "new_user@example.com"
status: "active"
createdAt: "2023-05-10T09:15:00Z"
accessToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
'400':
description:Solicitud no válida
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description:El usuario ya existe
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
- status
UserDetail:
allOf:
- $ref: '#/components/schemas/User'
- type: object
properties:
firstName:
type: string
description:Nombre
lastName:
type: string
description:Apellido
phone:
type: string
description:Número de teléfono
lastLogin:
type: string
format: date-time
description:Última hora de inicio de sesión
NewUser:
type: object
properties:
username:
type: string
description:Nombre de usuario
minLength: 3
maxLength: 50
email:
type: string
format: email
description:Correo electrónico del usuario
password:
type: string
format: password
description:Contraseña del usuario
minLength: 8
maxLength: 100
firstName:
type: string
description:Nombre
lastName:
type: string
description:Apellido
phone:
type: string
description:Número de teléfono
required:
- username
- password
UpdateUser:
type: object
properties:
email:
type: string
format: email
description:Correo electrónico del usuario
firstName:
type: string
description:Nombre
lastName:
type: string
description:Apellido
phone:
type: string
description:Número de teléfono
password:
type: string
format: password
description:Nueva contraseña (si se desea cambiar)
minLength: 8
maxLength: 100
Error:
type: object
properties:
code:
type: integer
format: int32
description:Código de error
message:
type: string
description:Mensaje de error
required:
- code
- message
responses:
UnauthorizedError:
description:Token de acceso perdido o no válido
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 401
message: "Acceso no autorizado"
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description:Autenticación mediante token Bearer JWT
security:
- bearerAuth: []
A continuación se presentan los componentes principales del documento:
1. Sección de información básica
- Título y descripción de la API: funciones básicas del sistema de gestión de usuarios
- Información de versión:1.0.0
- Información de contacto: información de contacto del equipo de soporte de API
- Licencia:Apache 2.0
2. Configuración del servidor
- Entorno de producción
- Entorno de preproducción
- Entorno de desarrollo
3. Clasificación de etiquetas de API
- Operaciones relacionadas con usuarios
- Operaciones relacionadas con autenticación
4. Rutas y operaciones
Esta API incluye los siguientes endpoints:
Gestión de usuarios
GET /users- Obtener lista de todos los usuarios (con soporte para paginación y filtrado)POST /users- Crear nuevo usuarioGET /users/{userId}- Obtener detalles de un usuario específicoPUT /users/{userId}- Actualizar información del usuarioDELETE /users/{userId}- Eliminar usuario
Servicio de autenticación
POST /auth/login- Inicio de sesión de usuarioPOST /auth/register- Registro de usuario
5. Modelo de datos
User- Información básica del usuarioUserDetail- Información detallada del usuarioNewUser- Cuerpo de solicitud para crear usuarioUpdateUser- Cuerpo de solicitud para actualizar usuarioError- Respuesta de error
6. Definición de seguridad
Utiliza token Bearer JWT para la autenticación de la API.
Este documento sigue la especificación OpenAPI 3.0.0, e incluye parámetros de solicitud completos, códigos de estado de respuesta, definiciones de modelos de datos y valores de ejemplo. Puedes copiar este documento YAML en Swagger Editor para ver el efecto visualizado, o integrarlo en tu proyecto.
Este documento puede servir como base para desarrollar tu API RESTful, y se puede ampliar y mejorar a medida que el proyecto evolucione.
Otras extensiones