Swagger dans 1C : Automatisation de la documentation API | Guide

# Swagger dans 1C : Génération automatique de documentation pour les services HTTP sans travail manuel

Tout développeur 1C a déjà connu cela : un intégrateur demande un exemple de structure JSON, s'interroge sur le format de date, ou exige une mise à jour de la documentation obsolète. Il existe une solution — intégrer Swagger à la plateforme 1C. Ce standard de facto pour les API REST automatise la documentation, la validation des paramètres et les tests. Contrairement aux solutions classiques où la documentation vit séparément du code, nous allons vous montrer comment faire en sorte que la spécification se mette à jour automatiquement à chaque changement de logique.

Les bases d'OpenAPI dans l'écosystème 1C : Pas de théorie, mais un modèle fonctionnel

Swagger (OpenAPI Specification) est plus qu'une UI interactive — c'est un système où la documentation fait partie intégrante du code. C'est crucial pour 1C, car la plateforme ne supporte pas nativement la génération de spécifications. Composants clés du workflow :

• Spécification au format YAML/JSON — le plan technique de l'API, décrivant les méthodes, paramètres et structures de données
• Générateur de SDK client — génération automatique d'enveloppes pour frontend ou systèmes externes
• Validation des requêtes — vérification en temps réel des données d'entrée par rapport à la description

Important de comprendre : Swagger dans 1C n'est pas un outil pour construire des API, mais une couche de documentation pour les services HTTP existants. Toute la logique métier reste dans vos gestionnaires, et l'extension ne fait que décrire leur interface.

Installation de l'extension Swagger-1C : Étapes critiques souvent négligées

Préparation de l'environnement

• Téléchargez la dernière version de l'extension depuis le dépôt officiel
• Dans le configurateur, créez une nouvelle extension nommée Swagger
• Chargez le fichier d'extension via Configuration → Load Configuration from File

Configuration du serveur web

C'est là que surgissent 80 % des problèmes. Après l'installation :

• Dans les paramètres de publication de la base de données, assurez-vous de cocher Publish HTTP services of extensions by default
• Redémarrez le serveur web (IIS/Apache/Nginx)
• Vérifiez la disponibilité de l'endpoint : http://<server_address>/hs/swagger/index.html?ui=RapiDoc

Si vous voyez une erreur 404 — retournez à la première étape. Sans publication des services HTTP, l'extension ne s'activera pas.

Implémentation du service WarehouseStocks : De la description au code fonctionnel

Modèle de nommage des modules

L'extension recherche les descriptions dans les modules communs suivant la règle : <HTTP_Service_Name>Description. Pour le service WarehouseStocks, créez le module WarehouseStocksDescription.

Description de la méthode 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

Notez les points suivants :

• Séparation claire des paramètres (URL, body, headers)
• Utilisation de descriptions multilingues via NStr
• Liaison des schémas à des objets spécifiques

Validation des données dans le gestionnaire

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

Points critiques :

• Validation des paramètres avant l'exécution de la logique métier
• Validation de la réponse après la formation des données
• Utilisation des codes de statut HTTP standards (404, 422)

Points clés pour les développeurs

• Documentation = code — les changements de logique se reflètent automatiquement dans l'UI Swagger
• CORS nécessite une configuration séparée — ajoutez les en-têtes Access-Control-Allow-Origin dans le gestionnaire
• Les types de données doivent correspondre — une chaîne en 1C ≠ entier dans la spec
• Les tests UI économisent 30 % du temps pour la coordination avec les intégrateurs
• RapiDoc corrige les problèmes d'affichage — utilisez le paramètre ?ui=RapiDoc en cas d'erreurs

Erreurs courantes et solutions

Problème : CORS bloque les requêtes navigateur

Solution : Ajoutez dans le gestionnaire de service HTTP :

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

Problème : Mauvais type de données dans la réponse

Symptôme : Swagger affiche un entier, mais 1C retourne une chaîne

Solution : Spécifiez explicitement le type dans la description de l'objet :

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

Problème : La description ne se met pas à jour après modifications

Cause : Cache du navigateur ou du serveur web

Solution : Ajoutez un paramètre GET de version : /index.html?v=2

Conclusion : Pourquoi cela fonctionne en production

Intégrer Swagger à 1C n'est pas un exercice théorique — c'est une solution pratique pour :

• Réduire le temps de coordination des API avec les systèmes externes
• Prévenir les erreurs dues aux écarts entre documentation et réalité
• Générer automatiquement des SDK clients pour le frontend

L'avantage principal de cette approche est l'interférence minimale avec votre architecture existante. L'extension fonctionne en temps réel, sans besoin de builds séparés ou de mises à jour manuelles de JSON. Pour les équipes traitant régulièrement avec des intégrateurs externes, cela réduit les coûts opérationnels de 40 %.

— Editorial Team