1C 中的 Swagger：API 文档自动化 | 指南

1C 中的 Swagger：无需手动工作的 HTTP 服务自动文档生成

每个 1C 开发者都遇到过这种情况：集成商要求提供 JSON 结构示例、询问日期格式，或者要求更新过时的文档。有个解决方案——将 Swagger 与 1C 平台集成。这个 REST API 的事実标准能自动生成文档、验证参数并进行测试。与文档与代码分离的典型解决方案不同，我们将展示如何让规范在逻辑变更时自动更新。

1C 生态系统中的 OpenAPI 基础：不是理论，而是实战模型

Swagger（OpenAPI Specification）不仅仅是一个交互式 UI——它是一个让文档成为代码库一部分的系统。这对 1C 至关重要，因为该平台不支持开箱即用的规范生成。主要工作流程组件：

• YAML/JSON 格式的规范 — API 的技术蓝图，描述方法、参数和数据结构
• 客户端 SDK 生成器 — 为前端或外部系统自动生成包装器
• 请求验证 — 实时检查输入数据是否符合描述

重要理解：1C 中的 Swagger 不是构建 API 的工具，而是现有 HTTP 服务上的文档层。所有业务逻辑保留在你的处理程序中，扩展仅描述其接口。

安装 Swagger-1C 扩展：常被忽略的关键步骤

环境准备

• 从官方仓库下载最新版本的扩展
• 在配置器中，创建一个名为 Swagger 的新扩展
• 通过 Configuration → Load Configuration from File 加载扩展文件

Web 服务器设置

安装后，这里是 80% 问题出现的地方：

• 在数据库发布参数中，确保选中 Publish HTTP services of extensions by default
• 重启 Web 服务器 (IIS/Apache/Nginx)
• 检查端点可用性：http://<server_address>/hs/swagger/index.html?ui=RapiDoc

如果看到 404 错误——返回第一步。没有发布 HTTP 服务，扩展不会激活。

实现仓库库存服务：从描述到工作代码

模块命名模板

扩展在通用模块中查找描述，遵循规则：<HTTP_Service_Name>Description。对于 WarehouseStocks 服务，创建 WarehouseStocksDescription 模块。

描述 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

注意以下内容：

• 参数清晰分离（URL、正文、标头）
• 通过 NStr 使用多语言描述
• 将模式绑定到特定对象

在处理程序中验证数据

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

关键点：

• 参数验证在执行业务逻辑之前
• 响应验证在形成数据之后
• 使用标准 HTTP 状态码 (404, 422)

开发者关键要点

• 文档 = 代码 — 逻辑变更自动反映在 Swagger UI 中
• CORS 需要单独设置 — 在处理程序中添加 Access-Control-Allow-Origin 标头
• 数据类型必须匹配 — 1C 中的字符串 ≠ 规范中的整数
• UI 测试节省 30% 与集成商协调时间
• RapiDoc 修复显示问题 — 出错时使用 ?ui=RapiDoc 参数

常见错误及修复

问题：CORS 阻止浏览器请求

修复： 在 HTTP 服务处理程序中添加：

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

问题：响应中数据类型错误

症状： Swagger 显示整数，但 1C 返回字符串

修复： 在对象描述中明确指定类型：

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

问题：编辑后描述未更新

原因： 浏览器或 Web 服务器缓存

修复： 添加版本 GET 参数：/index.html?v=2

结论：为什么这在生产环境中有效

将 Swagger 与 1C 集成不是理论练习——它是实用的解决方案，用于：

• 减少与外部系统的 API 协调时间
• 防止文档与实际不匹配导致的错误
• 为前端自动生成客户端 SDK

这种方法的主要优势是对现有架构干扰最小。扩展实时工作，无需单独构建或手动更新 JSON。对于经常与外部集成商打交道的团队，它可将运营成本降低 40%。

— Editorial Team