Swagger v 1C: automatizace dokumentování API | Průvodce

# Swagger v 1C: automatická generace dokumentace pro HTTP služby bez ruční práce

Každý vývojář 1C se setkal se situací: integrátor požaduje příklad struktury JSON, upřesňuje formát data nebo žádá o aktualizaci zastaralé dokumentace. Řešení existuje — integrace Swagger s platformou 1C. Tento de facto standard pro REST API automatizuje dokumentaci, kontrolu parametrů a testování. Na rozdíl od typických řešení, kde dokumentace žije odděleně od kódu, ukážeme, jak udělat tak, aby se specifikace aktualizovala automaticky při změně logiky.

Základy OpenAPI v ekosystému 1C: ne teorie, ale funkční model

Swagger (OpenAPI Specification) — to není jen interaktivní UI, ale systém, kde se dokumentace stává součástí kóbase. Pro 1C je to klíčové, protože platforma nepodporuje generování specifikací „z krabice“. Klíčové komponenty pracovního postupu:

• Specifikace ve formátu YAML/JSON — technický pasaport API, popisující metody, parametry a struktury dat
• Generátor klientských SDK — automatické vytváření obalů pro frontend nebo externí systémy
• Validace požadavků — kontrola shody vstupních dat s popisem v reálném čase

Důležité je pochopit: Swagger v 1C — to není nástroj pro vytváření API, ale vrstva dokumentace stávajících HTTP služeb. Veškerá business logika zůstává ve vašich obslužných rutinách, rozšíření jen popisuje jejich rozhraní.

Instalace rozšíření Swagger-1C: kritické kroky, které se často přehlížejí

Příprava prostředí

• Stáhněte aktuální verzi rozšíření z oficiálního repozitáře
• V konfigurátoru vytvořte nové rozšíření s názvem Swagger
• Nahrajte soubor rozšíření přes Konfigurace → Načíst konfiguraci ze souboru

Nastavení webového serveru

Zde se ukrývá 80 % problémů. Po instalaci:

• V parametrech publikování databáze povinně zaškrtněte „Publikovat HTTP služby rozšíření výchozí“
• Restartujte webový server (IIS/Apache/Nginx)
• Zkontrolujte dostupnost endpointu: http://<adres_database>/hs/swagger/index.html?ui=RapiDoc

Pokud vidíte chybu 404 — vraťte se k prvnímu bodu. Bez publikování HTTP služeb se rozšíření neaktivuje.

Implementace služby zůstatků: od popisu k funkčnímu kódu

Šablona pojmenování modulů

Rozšíření hledá popisy ve společných modulech podle pravidla: <Jméno_HTTP_služby>Popis. Pro službu WarehouseBalances vytvořte modul WarehouseBalancesDescription.

Popis metody 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

Všimněte si:

• Jasné oddělení parametrů (URL, tělo, hlavičky)
• Použití vícejazyčných popisů přes NStr
• Vazbu schémat na konkrétní objekty

Kontrola dat v obslužné rutině

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

Kritické body:

• Kontrola parametrů před provedením business logiky
• Validace odpovědi po vytvoření dat
• Použití standardních HTTP stavů (404, 422)

Co je důležité: klíčové závěry pro vývojáře

• Dokumentace = kód — změny v logice se automaticky projeví v Swagger UI
• CORS vyžaduje samostatné nastavení — přidejte hlavičky Access-Control-Allow-Origin do obslužné rutiny
• Typy dat musí shodovat — řetězec v 1C ≠ integer ve specifikaci
• Testování přes UI ušetří 30 % času na domluvy s integrátory
• RapiDoc řeší problémy zobrazení — použijte parametr ?ui=RapiDoc při chybách

Typické chyby a jejich řešení

Problém: CORS blokuje požadavky z prohlížeče

Řešení: Přidejte do obslužné rutiny HTTP služby:

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

Problém: Nesprávný typ dat v odpovědi

Příznak: Swagger ukazuje integer, ale 1C vrací řetězec

Řešení: V popisu objektu explicitně uveďte typ:

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

Problém: Popis se neaktualizuje po úpravách

Příčina: Cache prohlížeče nebo webového serveru

Řešení: Přidejte GET parametr s verzí: /index.html?v=2

Závěr: proč to funguje v produkci

Integrace Swagger s 1C — to není teoretické cvičení, ale funkční řešení pro:

• Zkrácení času na domluvy API s externími systémy
• Prevenci chyb kvůli nesouladu dokumentace a implementace
• Automatickou generaci klientských SDK pro frontend

Hlavní výhoda přístupu — minimální zásah do stávající architektury. Rozšíření pracuje v reálném čase, nevyžaduje samostatné sestavy ani ruční aktualizace JSON. Pro týmy, které pravidelně spolupracují s externími integrátory, to snižuje provozní náklady o 40 %.

— Editorial Team