Swagger in 1C: API Documentation Automation | Guide

Swagger in 1C: Automatic Documentation Generation for HTTP Services Without Manual Work

Every 1C developer has dealt with this: an integrator requests a JSON structure example, asks about the date format, or demands an update to outdated documentation. There's a solution—integrating Swagger with the 1C platform. This de facto standard for REST APIs automates documentation, parameter validation, and testing. Unlike typical solutions where documentation lives separately from the code, we'll show you how to make the specification update automatically whenever the logic changes.

OpenAPI Basics in the 1C Ecosystem: Not Theory, but a Working Model

Swagger (OpenAPI Specification) is more than just an interactive UI—it's a system where documentation becomes part of the codebase. This is crucial for 1C, as the platform doesn't support out-of-the-box specification generation. Key workflow components:

• Specification in YAML/JSON format — the API's technical blueprint, describing methods, parameters, and data structures
• Client SDK generator — automatic wrapper generation for frontend or external systems
• Request validation — real-time checking of input data against the description

Important to understand: Swagger in 1C isn't a tool for building APIs, but a documentation layer for existing HTTP services. All business logic stays in your handlers, and the extension simply describes their interface.

Installing the Swagger-1C Extension: Critical Steps Often Overlooked

Environment Preparation

• Download the latest version of the extension from the official repository
• In the configurator, create a new extension named Swagger
• Load the extension file via Configuration → Load Configuration from File

Web Server Setup

This is where 80% of problems crop up. After installation:

• In the database publication parameters, make sure to check Publish HTTP services of extensions by default
• Restart the web server (IIS/Apache/Nginx)
• Check endpoint availability: http://<server_address>/hs/swagger/index.html?ui=RapiDoc

If you see a 404 error—go back to the first step. Without publishing HTTP services, the extension won't activate.

Implementing the Warehouse Stocks Service: From Description to Working Code

Module Naming Template

The extension looks for descriptions in common modules following the rule: <HTTP_Service_Name>Description. For the WarehouseStocks service, create the WarehouseStocksDescription module.

Describing the GET /stocks Method

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

Note the following:

• Clear separation of parameters (URL, body, headers)
• Use of multilingual descriptions via NStr
• Binding schemas to specific objects

Validating Data in the 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

Critical points:

• Parameter validation before executing business logic
• Response validation after forming the data
• Use of standard HTTP status codes (404, 422)

Key Takeaways for Developers

• Documentation = code — changes in logic automatically reflect in Swagger UI
• CORS requires separate setup — add Access-Control-Allow-Origin headers in the handler
• Data types must match — a string in 1C ≠ integer in the spec
• UI testing saves 30% of time on coordinating with integrators
• RapiDoc fixes display issues — use the ?ui=RapiDoc parameter for errors

Common Errors and Fixes

Problem: CORS Blocks Browser Requests

Fix: Add to the HTTP service handler:

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

Problem: Wrong Data Type in Response

Symptom: Swagger shows integer, but 1C returns a string

Fix: Explicitly specify the type in the object description:

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

Problem: Description Doesn't Update After Edits

Cause: Browser or web server caching

Fix: Add a version GET parameter: /index.html?v=2

Conclusion: Why This Works in Production

Integrating Swagger with 1C isn't a theoretical exercise—it's a practical solution for:

• Reducing API coordination time with external systems
• Preventing errors from documentation-reality mismatches
• Automatically generating client SDKs for frontend

The main advantage of this approach is minimal interference with your existing architecture. The extension works in real time, without needing separate builds or manual JSON updates. For teams regularly dealing with external integrators, it cuts operational costs by 40%.

— Editorial Team