Swagger in 1C: Automatisierung der API-Dokumentation | Anleitung

# Swagger in 1C: Automatische Dokumentationserstellung für HTTP-Dienste ohne manuellen Aufwand

Jeder 1C-Entwickler kennt das: Ein Integrator fordert ein Beispiel für die JSON-Struktur an, fragt nach dem Datumsformat oder verlangt eine Aktualisierung der veralteten Dokumentation. Es gibt eine Lösung – die Integration von Swagger in die 1C-Plattform. Dieser De-facto-Standard für REST-APIs automatisiert die Dokumentation, Parameterüberprüfung und Tests. Im Gegensatz zu typischen Lösungen, bei denen die Dokumentation separat vom Code existiert, zeigen wir Ihnen, wie die Spezifikation automatisch aktualisiert wird, sobald sich die Logik ändert.

Grundlagen von OpenAPI im 1C-Ökosystem: Keine Theorie, sondern ein funktionierendes Modell

Swagger (OpenAPI Specification) ist mehr als nur eine interaktive UI – es ist ein System, in dem die Dokumentation Teil des Codebases wird. Das ist für 1C entscheidend, da die Plattform keine out-of-the-box Spezifikationserstellung unterstützt. Wichtige Workflow-Komponenten:

• Spezifikation im YAML/JSON-Format — der technische Bauplan der API, der Methoden, Parameter und Datenstrukturen beschreibt
• Client-SDK-Generator — automatische Generierung von Wrappers für Frontend oder externe Systeme
• Anfragenvalidierung — Echtzeitüberprüfung der Eingabedaten gegen die Beschreibung

Wichtig zu verstehen: Swagger in 1C ist kein Tool zum Erstellen von APIs, sondern eine Dokumentationsschicht für bestehende HTTP-Dienste. Alle Geschäftslogik bleibt in Ihren Handlern, und die Erweiterung beschreibt lediglich deren Schnittstelle.

Installation der Swagger-1C-Erweiterung: Kritische Schritte, die oft übersehen werden

Vorbereitung der Umgebung

• Laden Sie die neueste Version der Erweiterung aus dem offiziellen Repository herunter
• Im Konfigurator eine neue Erweiterung namens Swagger erstellen
• Die Erweiterungsdatei über Konfiguration → Konfiguration aus Datei laden laden

Einrichtung des Web-Servers

Hier treten 80 % der Probleme auf. Nach der Installation:

• In den Datenbankpublikationsparametern sicherstellen, HTTP-Dienste von Erweiterungen standardmäßig veröffentlichen anzuhaken
• Webserver neu starten (IIS/Apache/Nginx)
• Endpunktverfügbarkeit prüfen: http://<server_address>/hs/swagger/index.html?ui=RapiDoc

Wenn Sie einen 404-Fehler sehen – zurück zum ersten Schritt. Ohne Veröffentlichung der HTTP-Dienste wird die Erweiterung nicht aktiviert.

Implementierung des Lagerbestands-Dienstes: Von der Beschreibung zum lauffähigen Code

Namenskonvention für Module

Die Erweiterung sucht Beschreibungen in gemeinsamen Modulen nach der Regel: <HTTP_Service_Name>Description. Für den WarehouseStocks-Dienst erstellen Sie das WarehouseStocksDescription-Modul.

Beschreibung der GET /stocks-Methode

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

Beachten Sie Folgendes:

• Klare Trennung der Parameter (URL, Body, Header)
• Verwendung mehrsprachiger Beschreibungen via NStr
• Bindung von Schemata an spezifische Objekte

Datenvalidierung im Handler

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

Kritische Punkte:

• Parameterüberprüfung vor Ausführung der Geschäftslogik
• Antwortvalidierung nach Bildung der Daten
• Verwendung standardisierter HTTP-Statuscodes (404, 422)

Wichtige Erkenntnisse für Entwickler

• Dokumentation = Code — Änderungen in der Logik spiegeln sich automatisch in der Swagger-UI wider
• CORS erfordert separate Einrichtung — Access-Control-Allow-Origin-Header im Handler hinzufügen
• Datentypen müssen übereinstimmen — ein String in 1C ≠ Integer in der Spezifikation
• UI-Tests sparen 30 % der Zeit bei der Abstimmung mit Integratoren
• RapiDoc behebt Anzeigeprobleme — den ?ui=RapiDoc-Parameter bei Fehlern verwenden

Häufige Fehler und Lösungen

Problem: CORS blockiert Browser-Anfragen

Lösung: Im HTTP-Dienst-Handler hinzufügen:

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

Problem: Falscher Datentyp in der Antwort

Symptom: Swagger zeigt Integer an, aber 1C liefert einen String

Lösung: Typ explizit in der Objektbeschreibung angeben:

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

Problem: Beschreibung aktualisiert sich nach Bearbeitungen nicht

Ursache: Caching des Browsers oder Web-Servers

Lösung: Versions-GET-Parameter hinzufügen: /index.html?v=2

Fazit: Warum das in der Produktion funktioniert

Die Integration von Swagger in 1C ist kein theoretisches Experiment – es ist eine praktische Lösung für:

• Reduzierung der API-Abstimmungszeit mit externen Systemen
• Vermeidung von Fehlern durch Abweichungen zwischen Dokumentation und Realität
• Automatische Generierung von Client-SDKs für das Frontend

Der Hauptvorteil dieses Ansatzes ist die minimale Störung Ihrer bestehenden Architektur. Die Erweiterung arbeitet in Echtzeit, ohne separate Builds oder manuelle JSON-Aktualisierungen zu benötigen. Für Teams, die regelmäßig mit externen Integratoren zu tun haben, reduziert es die Betriebskosten um 40 %.

— Editorial Team