Componentes principales de Swagger
Swagger es un conjunto de herramientas de código abierto construido en torno a la especificación OpenAPI, utilizado para diseñar, construir, documentar y usar API RESTful.
Swagger proporciona una forma estandarizada de describir la estructura de una API, lo que permite que tanto los desarrolladores como las máquinas comprendan las funcionalidades de la API sin necesidad de acceder al código fuente u otra documentación.
El valor principal de Swagger radica en:
- Estandarización: proporciona un formato unificado de descripción de API
- Visualización: genera automáticamente documentación interactiva de API
- Testabilidad: permite probar los endpoints de la API directamente en la documentación
- Generación de código: admite la generación de código de cliente y servidor en múltiples lenguajes
Componentes principales de Swagger
| Componente | Entrada | Salida | Fase de aplicación |
|---|---|---|---|
| Swagger Editor | Escritura manual de YAML/JSON | Documentación de API con vista previa en tiempo real | Fase de diseño de API |
| Swagger UI | Archivo OpenAPI | Documentación web interactiva | Fase de desarrollo/pruebas |
| Swagger Codegen | Archivo OpenAPI | Código de cliente/servidor | Fase de colaboración entre frontend y backend |
Diagrama de flujo de colaboración de componentes:
Swagger Editor(设计API) ↓ OpenAPI 规范文件(YAML/JSON) ↓ Swagger UI(展示文档) 或 Swagger Codegen(生成代码)

Explicación detallada de los componentes principales de Swagger
1. Swagger Editor
Swagger Editor es un editor visual basado en navegador que se utiliza para escribir y previsualizar en tiempo real la especificación OpenAPI (en formato YAML/JSON).
Swagger Editor ofrece resaltado de sintaxis, autocompletado y validación de errores.
Las funciones de generación de código, guardado y exportación de Swagger Editor ahora están disponibles en SmartBear API Hub. Dirección de acceso:https://try.platform.smartbear.com/new-organization。
Casos de uso:
- Diseño rápido de prototipos de API
- Aprender la sintaxis de la especificación OpenAPI
Acceda al editor en línea Swagger Editor:https://editor.swagger.io/
Ingrese el siguiente código YAML (para definir un endpoint simple GET /users):
Ejemplo
openapi: 3.0.3
info:
title: Sistema de gestión de usuarios de EJEMPLO
version: 1.0.0
paths:
/users:
get:
summary: Obtener la lista de usuarios
responses:
'200':
description: Devuelve la lista de usuarios con éxito
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: integer
name:
type: string
El lado derecho mostrará en tiempo real la documentación de la API y la interfaz de usuario interactiva.

Swagger UI
Swagger UI convierte la especificación OpenAPI en documentación visual e interactiva, y permite probar la API directamente en el navegador.
Swagger UI genera automáticamente ejemplos de solicitudes, modelos de respuesta e interfaz de depuración.
Swagger UI: https://swagger.io/tools/swagger-ui/
Casos de uso:
- Compartir documentación de API en equipo
- Depuración de interfaces por parte de desarrolladores de frontend
Ejemplo de integración (con Node.js como ejemplo), instale las dependencias:
npm install swagger-ui-express swagger-jsdoc
Cree el archivo de configuración swagger.js:
Ejemplo
const options = {
definition: {
openapi: '3.0.0',
info: { title: 'API de usuario', version: '1.0.0' },
},
apis: ['./routes/*.js'], // Escanea los comentarios en el archivo de rutas
};
const swaggerSpec = swaggerJSDoc(options);
module.exports = swaggerSpec;
Monte la UI en Express:
Ejemplo
const swaggerUi = require('swagger-ui-express');
const swaggerSpec = require('./swagger');
const app = express();
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));
Visite http://localhost:3000/api-docs para ver la documentación.

Swagger Codegen
Swagger Codegen genera automáticamente SDK de cliente (como Java, Python) o código stub de servidor (como Spring, Flask) según la especificación OpenAPI.
Swagger Codegen admite plantillas personalizadas.
Página de descarga:https://swagger.io/tools/swagger-codegen/
Casos de uso:
- Generar rápidamente código de cliente para llamadas a API
- Desarrollo automatizado de interfaces de servidor
Ejemplo de operación (generar cliente Java desde línea de comandos), descargue Swagger Codegen CLI:
wget https://repo1.maven.org/maven2/io/swagger/codegen/v3/swagger-codegen-cli/3.0.35/swagger-codegen-cli-3.0.35.jar -O swagger-codegen-cli.jar
Genere el código:
java -jar swagger-codegen-cli.jar generate \ -i https://petstore.swagger.io/v2/swagger.json \ -l java \ -o ./petstore-api-client
Swagger Hub (extensión opcional)
Swagger Hub es la plataforma en la nube de Swagger que ofrece diseño colaborativo, gestión de versiones y documentación alojada.
Swagger Hub admite colaboración en equipo y gestión del ciclo de vida de las API.
Casos de uso:
- Gestión de proyectos de API a nivel empresarial
- Equipos distribuidos que necesitan colaboración en línea
Dirección de acceso:https://swagger.io/api-hub/
Otras extensiones