Swagger en 1C: Automatización de Documentación de API | Guía

# Swagger en 1C: Generación automática de documentación para servicios HTTP sin trabajo manual

Cada desarrollador de 1C se ha topado con esto: un integrador pide un ejemplo de estructura JSON, pregunta por el formato de fecha o exige actualizar la documentación obsoleta. Hay una solución: integrar Swagger con la plataforma 1C. Este estándar de facto para REST APIs automatiza la documentación, la validación de parámetros y las pruebas. A diferencia de las soluciones habituales donde la documentación vive aparte del código, te mostramos cómo hacer que la especificación se actualice automáticamente cada vez que cambie la lógica.

Fundamentos de OpenAPI en el ecosistema de 1C: No teoría, sino un modelo funcional

Swagger (OpenAPI Specification) es más que una interfaz interactiva: es un sistema donde la documentación forma parte del código base. Esto es clave para 1C, ya que la plataforma no genera especificaciones de forma nativa. Componentes clave del flujo de trabajo:

• Especificación en formato YAML/JSON — el plano técnico del API, que describe métodos, parámetros y estructuras de datos
• Generador de SDK para clientes — generación automática de wrappers para frontend o sistemas externos
• Validación de solicitudes — verificación en tiempo real de los datos de entrada contra la descripción

Importante entender: Swagger en 1C no es una herramienta para construir APIs, sino una capa de documentación para servicios HTTP existentes. Toda la lógica de negocio se mantiene en tus manejadores, y la extensión simplemente describe su interfaz.

Instalación de la extensión Swagger-1C: Pasos críticos que a menudo se pasan por alto

Preparación del entorno

• Descarga la versión más reciente de la extensión desde el repositorio oficial
• En el configurador, crea una nueva extensión llamada Swagger
• Carga el archivo de la extensión mediante Configuración → Cargar configuración desde archivo

Configuración del servidor web

Aquí surge el 80% de los problemas. Tras la instalación:

• En los parámetros de publicación de la base de datos, asegúrate de marcar Publicar servicios HTTP de extensiones por defecto
• Reinicia el servidor web (IIS/Apache/Nginx)
• Verifica la disponibilidad del endpoint: http://<server_address>/hs/swagger/index.html?ui=RapiDoc

Si ves un error 404, vuelve al primer paso. Sin publicar los servicios HTTP, la extensión no se activa.

Implementación del servicio de existencias de almacén: De la descripción al código funcional

Plantilla de nomenclatura de módulos

La extensión busca descripciones en módulos comunes siguiendo la regla: <Nombre_del_Servicio_HTTP>Descripción. Para el servicio WarehouseStocks, crea el módulo WarehouseStocksDescription.

Descripción del método GET /stocks

Function PoluchitDescriptionHTTPWithervisa() Eksport

    Methods = Swag_Description
        .Method("WarehouseBalancesGET")
            .DescriptionMethod("Ostatki tovarov on warehouses")
            .DetalnoeDescriptionMethod(NStr("ru = 'Receiving data by ostatkam on warehouses.'"))  
            .ParametrURL("storageCode")
                .DescriptionParametra("Code sklada, for example \"0897\"")
            .Body().TipTela("application/json")
                .WithkhemaTela("WarehouseBalancesGET")
                
        .Answer(200)
            .DescriptionOtveta("Success")
                .TipOtveta("application/json")
                .WithkhemaOtveta("WarehouseBalances_Answer")
                
        .Withformirovat();
        
    Return Methods;

EndFunction

Observa lo siguiente:

• Separación clara de parámetros (URL, body, headers)
• Uso de descripciones multilingües mediante NStr
• Vinculación de esquemas a objetos específicos

Validación de datos en el manejador

function stocksGET(Query)

    CheckResult = Swag_HTTPProcessing.ProveritParametry(
        "WarehouseBalances",
        "GET",
        Query
    );

    If Not PustayaWithtroka(CheckResult) Togda
        Return Swag_HTTPProcessing.PoluchitOtvetOshibki(CheckResult, Istina);
    KonetsEsli;

    // Osnovnaya logic
    BalanceArray = ModulObrabotkiNTTRWithervisov.PoluchitOstatki(Query.Parametry["storageCode"]);

    Answer = New NTTRWithervisOtvet(200);
    Answer.UstanovitTeloIzWithtroki(BalanceArray);

    Return Swag_HTTPProcessing.ProveritOtvet("WarehouseBalances", "GET", Answer);

EndFunction

Puntos críticos:

• Validación de parámetros antes de ejecutar la lógica de negocio
• Validación de respuesta después de formar los datos
• Uso de códigos de estado HTTP estándar (404, 422)

Lecciones clave para desarrolladores

• Documentación = código — los cambios en la lógica se reflejan automáticamente en la UI de Swagger
• CORS requiere configuración aparte — agrega cabeceras Access-Control-Allow-Origin en el manejador
• Los tipos de datos deben coincidir — una cadena en 1C ≠ entero en la especificación
• Pruebas en la UI ahorran 30% del tiempo en coordinación con integradores
• RapiDoc soluciona problemas de visualización — usa el parámetro ?ui=RapiDoc para errores

Errores comunes y soluciones

Problema: CORS bloquea solicitudes del navegador

Solución: Agrega al manejador del servicio HTTP:

Answer.SetHeader("Access-Control-Allow-Origin", "*");
Answer.SetHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");

Problema: Tipo de dato incorrecto en la respuesta

Síntoma: Swagger muestra entero, pero 1C devuelve una cadena

Solución: Especifica explícitamente el tipo en la descripción del objeto:

.Withvoystvo("quantity")
    .DescriptionWithvoystva("Count")
    .TipZnacheniya("integer")
    .Example(456)

Problema: La descripción no se actualiza tras ediciones

Causa: Caché del navegador o del servidor web

Solución: Agrega un parámetro GET de versión: /index.html?v=2

Conclusión: Por qué funciona en producción

Integrar Swagger con 1C no es un ejercicio teórico: es una solución práctica para:

• Reducir el tiempo de coordinación de APIs con sistemas externos
• Prevenir errores por discrepancias entre documentación y realidad
• Generar SDKs para clientes automáticamente para frontend

La principal ventaja de este enfoque es la interferencia mínima con tu arquitectura existente. La extensión funciona en tiempo real, sin necesidad de compilaciones separadas ni actualizaciones manuales de JSON. Para equipos que lidian regularmente con integradores externos, reduce los costos operativos en un 40%.

— Editorial Team