Swagger w 1C: automatyzacja dokumentowania API | Przewodnik

Swagger w 1C: automatyczna generacja dokumentacji dla serwisów HTTP bez ręcznej pracy

Każdy deweloper 1C stykał się z taką sytuacją: integrator żąda przykładu struktury JSON, dopytuje o format daty lub prosi o aktualizację przestarzałej dokumentacji. Rozwiązanie istnieje — integracja Swagger z platformą 1C. Ten de facto standard dla REST API automatyzuje dokumentowanie, walidację parametrów i testowanie. W odróżnieniu od typowych rozwiązań, gdzie dokumentacja istnieje osobno od kodu, pokażemy, jak sprawić, by specyfikacja aktualizowała się automatycznie przy każdej zmianie logiki.

Podstawy OpenAPI w ekosystemie 1C: nie teoria, a działający model

Swagger (OpenAPI Specification) to nie tylko interaktywny interfejs użytkownika, ale cały system, w którym dokumentacja staje się częścią bazy kodu. Dla 1C ma to kluczowe znaczenie, ponieważ platforma nie obsługuje generowania specyfikacji „prosto z pudełka”. Kluczowe elementy procesu:

• Specyfikacja w formacie YAML/JSON — techniczny paszport API opisujący metody, parametry i struktury danych
• Generator SDK klienckich — automatyczne tworzenie bindingów dla frontendu lub zewnętrznych systemów
• Walidacja zapytań — sprawdzanie zgodności danych wejściowych z opisem w czasie rzeczywistym

Ważne, by zrozumieć: Swagger w 1C to nie narzędzie do tworzenia API, lecz warstwa dokumentacji istniejących serwisów HTTP. Cała logika biznesowa pozostaje w twoich handlerach, a rozszerzenie jedynie opisuje ich interfejs.

Instalacja rozszerzenia Swagger-1C: kluczowe kroki, które często się pomija

Przygotowanie środowiska

• Pobierz aktualną wersję rozszerzenia z oficjalnego repozytorium
• W konfiguratorze utwórz nowe rozszerzenie o nazwie Swagger
• Załaduj plik rozszerzenia przez Konfiguracja → Załaduj konfigurację z pliku

Konfiguracja serwera WWW

Tu kryje się 80% problemów. Po instalacji:

• W parametrach publikacji bazy koniecznie zaznacz opcję „Publikuj serwisy HTTP rozszerzeń domyślnie”
• Zrestartuj serwer WWW (IIS/Apache/Nginx)
• Sprawdź dostępność endpointu: http://<adres_database>/hs/swagger/index.html?ui=RapiDoc

Jeśli widzisz błąd 404 — wróć do pierwszego punktu. Bez publikacji serwisów HTTP rozszerzenie się nie aktywuje.

Implementacja serwisu stanów magazynowych: od opisu do działającego kodu

Szablon nazewnictwa modułów

Rozszerzenie szuka opisów we wspólnych modułach według reguły: <Nazwa_serwisu_HTTP>Opis. Dla serwisu WarehouseBalances utwórz moduł WarehouseBalancesDescription.

Opis 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

Zwróć uwagę na:

• Wyraźne rozdzielenie parametrów (URL, ciało, nagłówki)
• Użycie wielojęzycznych opisów przez NStr
• Powiązanie schematów z konkretnymi obiektami

Walidacja danych w handlerze

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

Kluczowe aspekty:

• Walidacja parametrów przed wykonaniem logiki biznesowej
• Walidacja odpowiedzi po sformowaniu danych
• Użycie standardowych kodów HTTP (404, 422)

Co najważniejsze: kluczowe wnioski dla deweloperów

• Dokumentacja = kod — zmiany w logice automatycznie odzwierciedlą się w Swagger UI
• CORS wymaga osobnej konfiguracji — dodaj nagłówki Access-Control-Allow-Origin w handlerze
• Typy danych muszą się zgadzać — ciąg w 1C ≠ integer w specyfikacji
• Testowanie przez UI oszczędza 30% czasu na uzgodnienia z integratorami
• RapiDoc rozwiązuje problemy z wyświetlaniem — używaj parametru ?ui=RapiDoc przy błędach

Typowe błędy i ich naprawa

Problem: CORS blokuje zapytania z przeglądarki

Rozwiązanie: Dodaj w handlerze serwisu HTTP:

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

Problem: Nieprawidłowy typ danych w odpowiedzi

Objaw: Swagger pokazuje integer, a 1C zwraca ciąg

Rozwiązanie: W opisie obiektu jawnie podaj typ:

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

Problem: Opis nie aktualizuje się po edycji

Przyczyna: Buforowanie przeglądarki lub serwera WWW

Rozwiązanie: Dodaj parametr GET z wersją: /index.html?v=2

Podsumowanie: dlaczego to działa w produkcji

Integracja Swagger z 1C to nie akademickie ćwiczenie, lecz praktyczne rozwiązanie dla:

• Skrócenia czasu na uzgodnienia API z zewnętrznymi systemami
• Zapobiegania błędom z powodu rozbieżności dokumentacji i implementacji
• Automatycznej generacji SDK klienckich dla frontendu

Główna zaleta podejścia — minimalna ingerencja w istniejącą architekturę. Rozszerzenie działa w czasie rzeczywistym, bez potrzeby osobnych buildów czy ręcznej aktualizacji JSON. Dla zespołów regularnie współpracujących z zewnętrznymi integratorami to redukcja kosztów operacyjnych o 40%.

— Editorial Team