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

ComponenteEntradaSalidaFase de aplicación
Swagger EditorEscritura manual de YAML/JSONDocumentación de API con vista previa en tiempo realFase de diseño de API
Swagger UIArchivo OpenAPIDocumentación web interactivaFase de desarrollo/pruebas
Swagger CodegenArchivo OpenAPICódigo de cliente/servidorFase 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

span style="color: green;">
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 swaggerJSDoc = require('swagger-jsdoc');
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 express = require('express');
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