Contrats et compatibilité
Un contrat décrit la structure promise par une opération d'API. Echo réunit sa méthode, son chemin, son document et ses versions publiées. Un mock peut générer des données à partir du contrat et une application peut se lier à une version pour déclarer sa dépendance. Publier un contrat ne déploie ni ne teste une API en cours d'exécution.
Créer et publier
Ouvrez Contrats dans Maestro, créez le contrat et ouvrez Publier une version. Collez un document de contrat Echo et vérifiez-le avant de publier. Ce champ attend le JSON d'un document Echo, pas une réponse d'exemple ni un JSON Schema non converti. La conversion des schémas est disponible dans l'éditeur de routes de mocks.
Les versions publiées sont des instantanés numérotés. La liaison d'une application enregistre la version convenue. Le diff web montre les chemins modifiés, les raisons et des verdicts distincts pour les consommateurs et les fournisseurs. Réutiliser un contenu déjà publié peut renvoyer une ancienne version existante au lieu d'en créer une autre.
Lire dans le bon sens
La liaison Consumes indique que l'application appelle l'opération. Provides indique qu'elle la fournit. La comparaison distingue les changements de requête et de réponse et évalue chaque côté.
| Changement | Consommateur | Fournisseur |
|---|---|---|
| Ajouter un champ facultatif à la requête | Sûr | Sûr |
| Ajouter un champ obligatoire à la requête | Incompatible | Incompatible |
| Ajouter un champ obligatoire à la réponse | Sûr | Incompatible |
| Supprimer un champ de réponse ou changer son type | Incompatible | Incompatible |
| Ajouter un champ facultatif à la réponse | Conditionnel | Sûr |
Ce sont les verdicts du classificateur actuel. Un champ facultatif supplémentaire dans la réponse est conditionnel, car JsonUnmappedMemberHandling.Disallow refuse les champs inconnus. Lisez la condition et sa raison dans le diff. Safe signifie qu'aucune incompatibilité n'a été détectée de ce côté ; Warning demande une vérification ; Breaking signale une incompatibilité ; ConditionalBreaking dépend de la condition indiquée. Un verdict inconnu ne vaut pas approbation.
Vérifier avant d'accepter
Créer, publier et comparer des contrats dans Maestro est compris dans tous les forfaits Echo, Free compris. Publier depuis votre propre code nécessite une clé d'application ; créer une nouvelle clé dans Applications exige Echo Pro ou Pro AI et Echo/ManageHosting, autorisation attribuée par défaut à l'administrateur de l'organisation. Un fournisseur peut publier avec EchoContractPublicationClient, dans Gapfy.Echo.Contracts. Créez d'abord le contrat et la liaison Provides, puis utilisez une clé avec PublishOwnedContracts. Le client publie une version d'un contrat appartenant à l'application ; il ne crée pas de contrat et n'en prend pas la propriété.
La publication est terminée avant le retour des résultats de compatibilité. Un verdict incompatible ne l'annule pas. Vérifiez les différences avant de modifier un consommateur ou d'accepter une nouvelle référence.
Gapfy.Echo.Testing compare les contrats consommés à des instantanés vérifiés dans votre dépôt. Il peut faire échouer la CI lorsqu'un changement casse ce consommateur. Il ne teste pas l'API en cours d'exécution et ne valide pas les contrats fournis par votre application.
Construire un contrat de réponse sur le bureau
Ouvrez une route de mock et choisissez le mode de réponse Contrat. Partez d'un exemple JSON, examinez la structure déduite et vérifiez les ambiguïtés avant d'enregistrer. Sélectionnez un champ pour choisir un générateur compatible, puis vérifiez les aperçus avec un chemin de requête représentatif. Un exemple enregistré est un point de départ ; il ne décrit pas automatiquement toutes les réponses possibles.
Ajoutez des scénarios nommés pour des cas comme un résultat vide ou une opération refusée. Donnez un exemple à chaque scénario et sélectionnez-le pour examiner la réponse générée. Envoyez X-Echo-Scenario: empty pour demander un scénario nommé empty ; omettez l'en-tête pour utiliser la réponse par défaut. X-Echo-Seed permet de reproduire la génération aléatoire. Une seed fixe ne fige pas les générateurs utilisant la date actuelle. Une route attachée à une version publiée ne peut pas modifier cette version sur place.
Importer des modèles sans les réécrire
Avec un compte connecté et une connexion réseau, ouvrez Importer et exporter des modèles dans l'éditeur de contrats du bureau.
- Choisissez C#, TypeScript, JavaScript, Java, Python ou JSON Schema.
- Collez le code ou ouvrez les fichiers associés ensemble. Incluez les types référencés et indiquez le type racine s'il en existe plusieurs.
- Pour C#, choisissez si les propriétés doivent utiliser camelCase. Les noms JSON explicites sont prioritaires.
- Vérifiez l'aperçu de conversion. Lisez le document, le schema et les diagnostics avant d'appliquer.
- Appliquez l'aperçu réussi à la route. Fermer le dialogue ou une conversion en échec laisse la route inchangée. Modifier l'entrée exige un nouvel aperçu.
Utilisez l'exemple du langage choisi pour vérifier la structure attendue avant d'importer votre modèle.
| Format | Contenu à fournir |
|---|---|
| C# | DTOs et types référencés |
| TypeScript | Interfaces, alias de types ou champs publics typés |
| JavaScript | Métadonnées de schema statique littéral ou déclarations TypeScript .d.ts associées |
| Java | DTOs à champs publics ou records |
| Python | Dataclasses avec annotations de type |
| JSON Schema | Un schema explicite utilisant la structure de contrat prise en charge |
La conversion lit le code sans l'exécuter. Les dépendances manquantes et les constructions non prises en charge produisent des diagnostics. Les valeurs JavaScript à l'exécution ne suffisent pas pour déduire un modèle complet. Des sérialiseurs personnalisés, du polymorphisme ou des structures récursives peuvent nécessiter un schema explicite compatible. Les schemas importés restent associés au contrat lorsque vous modifiez l'exemple ou le chemin de la route ; mettez leur structure à jour par import plutôt qu'en remplaçant les générateurs individuellement.
Exporter des modèles pour une autre application
Choisissez le langage de sortie et exportez le contrat actuel. Examinez les fichiers générés, copiez-en un ou enregistrez le ZIP complet, qui contient contract.schema.json. Les mêmes six formats sont disponibles à l'export. L'export lit le document actuel et ne publie pas de nouvelle version.
Vérifiez les diagnostics sur la précision numérique et la distinction entre champs absents et nuls. Les types générés n'imposent pas seuls toutes les règles de plages, d'enums ou de propriétés supplémentaires ; conservez une validation de schema là où votre application en a besoin. L'export Python fournit from_dict et to_dict ; les valeurs Decimal nécessitent un encodeur JSON adapté.
Étapes suivantes
Reliez votre application avec applications et clés, ou utilisez le document pour servir des mocks publiés.