1C에서 Swagger: API 문서 자동화 | 가이드

1C에서의 Swagger: 수동 작업 없이 HTTP 서비스를 위한 자동 문서 생성

모든 1C 개발자가 겪어본 문제입니다: 통합 담당자가 JSON 구조 예시를 요청하거나 날짜 형식에 대해 물어보거나, 오래된 문서를 업데이트해 달라고 요구하죠. 해결책이 있습니다—1C 플랫폼에 Swagger를 통합하는 것입니다. REST API의 사실상 표준인 이 도구는 문서화, 매개변수 검증, 테스트를 자동화합니다. 일반적인 솔루션처럼 문서가 코드와 분리되어 존재하는 대신, 로직이 변경될 때마다 사양이 자동으로 업데이트되도록 구현하는 방법을 보여드리겠습니다.

1C 생태계에서의 OpenAPI 기초: 이론이 아닌 작동하는 모델

Swagger (OpenAPI Specification)는 단순한 대화형 UI가 아닙니다—문서가 코드베이스의 일부가 되는 시스템입니다. 1C에서 이는 매우 중요합니다. 플랫폼이 기본적으로 사양 생성을 지원하지 않기 때문이죠. 주요 워크플로 구성 요소:

• YAML/JSON 형식의 사양 — API의 기술 청사진으로, 메서드, 매개변수, 데이터 구조를 설명
• 클라이언트 SDK 생성기 — 프론트엔드나 외부 시스템을 위한 자동 래퍼 생성
• 요청 검증 — 설명에 따라 입력 데이터를 실시간으로 확인

중요한 점: 1C에서의 Swagger는 API를 구축하는 도구가 아니라 기존 HTTP 서비스를 위한 문서화 레이어입니다. 모든 비즈니스 로직은 핸들러에 그대로 두고, 확장은 인터페이스만 설명할 뿐입니다.

Swagger-1C 확장 설치: 자주 간과되는 핵심 단계

환경 준비

• 공식 저장소에서 최신 버전의 확장을 다운로드
• 구성도 편집기에서 Swagger라는 이름의 새 확장을 생성
• 구성 → 파일에서 구성 로드를 통해 확장 파일을 불러옴

웹 서버 설정

문제가 발생하는 경우의 80%가 여기에 있습니다. 설치 후:

• 데이터베이스 게시 매개변수에서 반드시 확장의 HTTP 서비스를 기본으로 게시 체크
• 웹 서버 (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, body, headers)의 명확한 분리
• 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)

문제: 수정 후 설명이 업데이트 안 됨

원인: 브라우저나 웹 서버 캐싱

해결: 버전 GET 매개변수 추가: /index.html?v=2

결론: 프로덕션에서 작동하는 이유

1C에 Swagger를 통합하는 것은 이론적 연습이 아닙니다—실제 솔루션으로:

• 외부 시스템과의 API 조율 시간 단축
• 문서-현실 불일치로 인한 오류 방지
• 프론트엔드를 위한 클라이언트 SDK 자동 생성

이 접근의 최대 장점은 기존 아키텍처에 최소 간섭입니다. 확장은 별도 빌드나 수동 JSON 업데이트 없이 실시간으로 작동합니다. 외부 통합 담당자와 정기적으로 일하는 팀에게 운영 비용을 40% 절감해 줍니다.

— Editorial Team