DocDriven

Qu’est-ce que DocDriven ?

DocDriven est une plateforme de conception d’API visuelle destinée aux équipes front-end, back-end, produit et design, gérée par l’entreprise danoise Nordicode ApS. Elle regroupe la conception des interfaces, la documentation, les services Mock, les revues, le suivi des modifications et la génération de code par IA dans un espace de travail partagé.

Ici, « conception » fait référence à la conception des points d’extrémité, des requêtes, des réponses et des schémas de données, et non à la création d’images, de logos ou de matériaux d’interface. Elle permet d’aligner les contrats API avant le développement officiel, afin de réduire les temps d’attente entre le front-end et le back-end ainsi que les modifications destructrices.

Aperçu des fonctions principales

Conception d’une API de visualisation

L’équipe peut créer des points de terminaison, des méthodes, des paramètres, des corps de requête, des réponses et des modèles de données dans l’interface, ce qui réduit les erreurs de structure lors de la modification directe du YAML. La complétion automatique et les suggestions basées sur les attributs existants aident à maintenir une cohérence entre les noms et le schéma.

• Les développeurs backend peuvent définir les ressources, le modèle d’erreurs et la stratégie de versionnement avant de coder.
• Les développeurs front-end peuvent vérifier à l’avance les champs requis et les flux d’interaction de la page.
• Le gestionnaire de produit peut consulter l’avancement des interfaces, les responsables et les problèmes non résolus.
• Les concepteurs d’interface peuvent vérifier si les données nécessaires à l’interface sont déjà prises en compte dans le contrat.
• Les visiteurs extérieurs peuvent participer à l’évaluation de projets spécifiques sans avoir besoin des droits sur l’ensemble de l’espace de travail.

L’édition visuelle ne peut pas remplacer la gouvernance des API. L’équipe doit toujours définir les règles d’authentification, d’autorisation, d’identité, de pagination, de codes d’erreur, de limitation de vitesse et de compatibilité.

Importation OpenAPI et documentation unifiée

Un nouveau projet peut commencer à partir de zéro ou importer des spécifications OpenAPI existantes. Cela permet de regrouper les interfaces internes et externes dispersées dans un espace de travail unique, servant de contrat consulté conjointement par le front-end, le back-end et les parties prenantes.

1. Créer des espaces de travail et des projets, ou choisir d’importer des normes existantes.
2. Vérifier que les endpoints, le schéma, les exemples et les définitions de sécurité ont été importés complètement.
3. Explications complémentaires sur les opérations, réponses aux erreurs et conditions limites.
4. Inviter des membres ou des visiteurs externes à évaluer et attribuer les problèmes en attente de traitement.
5. Publier la version API confirmée et établir une baseline des modifications.
6. Permettez à l’interface utilisateur de se connecter au serveur d’imitation, tandis que le backend est implémenté conformément au contrat.

Une importation réussie ne signifie pas que la sémantique normative est entièrement correcte. Les références circulaires, les extensions personnalisées, les mécanismes de sécurité et les modèles de polymorphisme complexes nécessitent des tests distincts.

Comment utiliser un serveur d’émulation

DocDriven permet de créer en temps réel un serveur mock cloud basé sur la conception de l’API, permettant aux appelsants de tester les requêtes et les réponses avant que le backend réel ne soit prêt. Les tests frontend, mobiles et automatisés peuvent fonctionner en parallèle autour du même contrat.

• Pour répondre à la définition, des exemples de succès représentatifs, d’échecs de validation, d’accès non autorisé et d’erreurs serveur sont fournis.
• Ne pas inscrire de clés de production, d’informations personnelles réelles ou de données clients dans les exemples.
• Vérifier si le code d’état, les en-têtes et le délai de la réponse Mock couvrent la logique du client.
• Après le déploiement du backend, on utilise des tests par contrat pour comparer la mise en œuvre réelle avec la conception.

Le serveur d’essai n’est qu’un service simulé ; il ne prouve pas que les performances, la sécurité, les transactions et la cohérence des données du backend réel répondent aux exigences.

Collaboration en temps réel et gestion des responsabilités

Les membres de l’équipe peuvent consulter les modifications de plan, commenter les propositions d’interface, signaler des problèmes et désigner un responsable. Les visiteurs du projet ne peuvent accéder qu’aux projets auxquels ils ont été invités et ne peuvent pas consulter d’autres projets ni gérer les paramètres de l’espace de travail.

Le rapport d’évaluation doit indiquer les raisons de la décision, les impacts de compatibilité et le plan de migration, et non se contenter de marquer l’opération comme terminée. Lorsqu’il s’agit d’API publiques ou partenariales, des procédures formelles d’approbation et de déploiement doivent également être mises en place.

Changelog et Baseline

Baseline capture l’état de l’API à un moment donné et le compare aux versions ultérieures. Les différences sont classées en fonction des points d’entrée ou des schémas ajoutés, supprimés ou modifiés, ce qui aide l’équipe à détecter rapidement les changements susceptibles de perturber les clients.

• Établir une ligne de base claire avant la publication stable.
• Vérifier la suppression de champs, les modifications de type, l’état obligatoire et les changements dans la structure de la requête.
• Définir de nouvelles versions et des délais de migration pour les modifications destructives.
• Ajouter le contexte métier, la date de publication et les actions de mise à niveau dans le Changelog.
• Intégrer l’évaluation des différences dans le processus de pull request ou de publication.

La détection automatique des différences permet de repérer les changements structurels, mais elle ne comprend pas nécessairement la sémantique métier. Les modifications de la signification des champs, des valeurs par défaut ou des droits peuvent également affecter l’appelant, même si le schéma reste inchangé.

AI Code Assistant

Code Assistant prend en compte les fichiers d’exemple et la configuration de l’équipe dans le répertoire GitHub pour générer du code pour les endpoints ou les schémas de DocDriven. Son objectif est de créer des implémentations de base en suivant les conventions existantes, plutôt que de gérer entièrement la logique métier de manière autonome.

Exigences du profil

Le répertoire racine du entrepôt nécessite un fichier docdriven.config.json ; chaque modèle contient un nom, un fichier d’exemple, un répertoire de sortie et un type cible. Le type cible peut être Endpoints ou Schemas ; le fichier d’exemple sert à guider la structure et le style du code généré.

Mode de sortie

• Créer une Pull Request pour que les développeurs la examinent avant de la fusionner.
• Soumettre à la branche actuellement sélectionnée.
• Soumettre à d’autres branches ou à d’autres dépôts autorisés.
• Voir le processus de génération, les échecs et l’état de finition sur la page de journal.

Privilégiez les Pull Request et faites en sorte que les tests, l’analyse statique et l’examen manuel assurent une vérification conjointe. Le code généré peut contenir des erreurs, des droits excessifs, un traitement non sécurisé des entrées ou des implémentations non conformes aux règles métier.

Connexion et sécurité GitHub

Pour utiliser Code Assistant, une autorisation GitHub est nécessaire, afin que DocDriven puisse accéder aux dépôts, lire des exemples de code et soumettre du contenu généré. La portée de cette autorisation a un impact direct sur le code privé et la sécurité de la chaîne d’approvisionnement.

• Autoriser uniquement les organisations et entrepôts qui en ont vraiment besoin.
• Utilisation de branches dédiées, de la branche principale protégée et d’une revue obligatoire des Pull Request.
• Ne placez pas les clés dans les fichiers d’exemple, la configuration ou les journaux.
• Vérifiez régulièrement les permissions des applications GitHub et annulez les connexions qui ne sont plus utilisées.
• Vérification des vulnérabilités liées à la génération, des licences et des paquets malveillants.
• Les droits d’accès sont révoqués immédiatement en cas de départ, de fin de projet ou de cessation de la période d’essai.

Prix et forfaits

Aucune carte de crédit n’est requise pour l’essai ; une fois celui-ci terminé, il est obligatoire de choisir un forfait payant, sinon le compte sera suspendu jusqu’à ce qu’une abonnement soit souscrit ou que le compte soit fermé. Les prix affichés pour les équipes peuvent varier en fonction du paiement mensuel ou annuel, des taxes et de la région ; au moins trois postes signifient que le coût minimal pour l’équipe est supérieur au prix d’un poste individuel.

La mise à niveau est facturée proportionnellement au cycle en cours, tandis que la baisse de niveau prend effet au début du cycle de facturation suivant. Les pages publiques ne précisent pas de règles claires de remboursement ; il convient de vérifier avant le paiement les modalités de renouvellement, d’annulation, des cycles non utilisés et du traitement des taxes.

Confidentialité et traitement des données

L’entité responsable mentionnée dans la politique de confidentialité est Nordicode ApS, avec une date de mise à jour en décembre 2023. La plateforme traite les noms, adresses e-mail, comptes, informations de paiement et d’utilisation ; les données de paiement sont gérées par Stripe, et les conditions de service indiquent que le système est hébergé en Allemagne.

• Les services peuvent utiliser les informations de compte pour l’authentification, la livraison, la communication, la sécurité et l’amélioration.
• Les utilisateurs peuvent demander, conformément à la législation en vigueur, l’accès, la mise à jour ou la suppression de leurs données personnelles.
• La plateforme déclare avoir adopté des mesures organisationnelles et techniques, mais ne garantit pas l’élimination de tous les risques.
• Les services ne sont pas conçus conformément aux réglementations sectorielles spécifiques telles que HIPAA ou FISMA ; les équipes de régulation doivent être prudentes.
• Les dépôts GitHub, la conception de l’API et la génération de code peuvent contenir des secrets commerciaux ; une vérification du fournisseur doit être effectuée au préalable.

La page de confidentialité ne précise pas suffisamment les fournisseurs de modèles utilisés par AI Code Assistant, la durée de conservation du code et les finalités d’entraînement. Avant d’accéder à un dépôt privé, il convient de confirmer avec le service des ventes le protocole de traitement des données, les sous-traitants, la suppression des sauvegardes et la politique relative aux données des modèles.

Conditions, droits d’auteur et restrictions commerciales

Les conditions permettent d’utiliser les services à des fins internes, dans le respect des règles en vigueur, tout en conservant les droits sur le code de la plateforme, les bases de données, la conception et la marque. La plateforme n’est pas une bibliothèque de code open source, et l’abonnement payant ne donne pas le droit de copier ou de revendre ses services.

• L’utilisateur doit s’assurer que les API, le code et le contenu téléchargés disposent des droits nécessaires.
• Les suggestions soumises directement peuvent être transférées aux opérateurs selon les conditions prévues ; il convient d’évaluer cela avant d’envoyer des idées confidentielles.
• Les contributions publiques peuvent accorder des licences d’utilisation très larges ; les designs privés ne doivent pas être placés dans l’espace public.
• Les services peuvent faire l’objet de modifications, d’interruptions ou de résiliation ; l’équipe doit exporter les spécifications clés et en effectuer ses propres sauvegardes.
• Les clauses sont soumises à la loi danoise, et les entreprises multirégionales doivent évaluer les responsabilités liées aux contrats et aux données.

Plateforme, API et statut open source

Adapté aux utilisateurs et aux scénarios

• Équipe backend : Unifier les ressources, les schémas, les erreurs et les règles de version avant la mise en œuvre.
• Équipes frontend et mobile : développer et valider l’interface à l’avance à l’aide d’un serveur de simulation.
• Manager de produit : Suivre le plan des interfaces, évaluer les problèmes et les responsables.
• Équipe d’ingénierie de plateforme : maintenir la cohérence de plusieurs API internes et externes.
• Responsable technique : examiner les écarts par rapport à la ligne de base et contrôler les modifications destructrices.
• Équipes utilisant GitHub : générer une implémentation de modèle révisable selon le style de code existant.

Avantages et limites des capacités

Avantages principaux

• Placer la conception de l’API, les mocks, la collaboration, le suivi des modifications et la génération de code dans le même flux de travail.
• L’édition visuelle abaisse les barrières à la participation des rôles non backend à l’évaluation des interfaces.
• Baseline rend les différences entre les endpoints et le schema plus intuitives.
• Code Assistant utilise des exemples de entrepôts et des contraintes de configuration pour l’affichage du style.
• Essai complet de 30 jours pour valider avec des équipes réelles.

Principales restrictions

• Le code généré par l’IA doit encore faire l’objet d’une revue, de tests et de vérifications de sécurité.
• Le programme Team nécessitant au moins trois places n’est pas adapté aux personnes qui n’ont qu’un seul compte.
• Un serveur de simulation ne peut pas remplacer les tests sur un backend réel.
• Fournisseurs de modèles non divulgués, détails du traitement du code, API de la plateforme et code source.
• Les services ne sont pas conçus pour un cadre réglementaire particulièrement strict.
• Le document est toujours indiqué comme en cours d’amélioration continue, et certaines limites pourraient nécessiter une confirmation auprès du service d’assistance.

Questions fréquentes

DocDriven est-il un outil de conception d’interface ?

Non. Il est conçu pour les points d’entrée API, les requêtes, les réponses et les modèles de données, et il aide les parties frontale et back-end à collaborer autour du contrat d’interface.

Est-ce qu’une carte de crédit est nécessaire pour la période d’essai ?

Ce n’est pas nécessaire. L’essai de 30 jours offre une seule zone de travail et toutes les fonctionnalités ; à son terme, le compte est suspendu en l’absence de paiement.

Combien de personnes sont nécessaires au minimum pour un projet Team ?

La page actuelle exige au moins 3 utilisateurs payants, et il est possible d’inviter un nombre illimité de visiteurs. Le montant total réel doit être confirmé sur la page de paiement.

Est-il possible d’importer une OpenAPI existante ?

Il est possible de créer des projets à partir des spécifications OpenAPI existantes. Après importation, il faut encore vérifier les extensions personnalisées, les définitions de sécurité et les modèles complexes.

Un serveur de simulation peut-il servir de backend en production ?

Non. Il est utilisé pour la conception par simulation, le développement parallèle frontend et les tests de contrat, mais ne dispose pas de logique métier ni de garanties de données pour un environnement de production.

L’IA va-t-elle modifier directement la branche principale ?

Le mode de sortie peut être configuré en Pull Request, sur la branche actuelle ou sur une autre branche par rapport au répertoire. L’équipe de production doit utiliser des branches protégées et un examen obligatoire.

Le code généré respectera-t-il les normes de l’équipe ?

Code Assistant se réfère aux fichiers de configuration et aux exemples de code, mais peut tout de même s’éloigner des règles. Il est nécessaire d’exécuter le formatage, les tests et une revue manuelle.

DocDriven est-il open source ?

Ce n’est pas un produit open source vérifiable. Le fait de prendre en charge OpenAPI et l’intégration avec GitHub ne signifie pas que le code source de la plateforme est accessible.

Y a-t-il une API pour les plateformes publiques ?

Aucune API ou SDK DocDriven destiné aux développeurs ordinaires n’a été identifié pour le moment. Lorsqu’une automatisation est nécessaire, il convient d’abord de se renseigner auprès de l’équipe produit.

Est-ce adapté aux données médicales ou hautement réglementées ?

Les conditions stipulent clairement que le service n’a pas été conçu pour répondre aux réglementations spécifiques de certains secteurs. Lorsqu’il s’agit d’interfaces ou de codes soumis à réglementation, une vérification de conformité et un examen contractuel doivent être effectués avant toute intégration.

Résumé

DocDriven convient aux équipes qui souhaitent établir un contrat API partagé avant le codage, et réduire les coûts de collaboration grâce à des mocks, au suivi des différences et à du code modèle généré par l’IA. Avant l’achat, il convient de vérifier attentivement les droits GitHub, la politique de données des modèles, le nombre minimal d’utilisateurs et le processus d’exportation des sauvegardes.