Comment créer une documentation API dans Postman?

how create api documentation postman

Ce didacticiel explique comment créer une documentation élégante et stylée avec un minimum d'efforts à l'aide de la prise en charge de la documentation API fournie par Postman Tool:

Pour toute API, interne ou publique, la documentation est l'un des ingrédients les plus essentiels de son succès.

La raison principale en est que la documentation est la façon dont vous communiquez avec vos utilisateurs.

• Comment utiliser votre API?
• Quels sont tous les codes d'état pris en charge?
• Quels sont les codes d'erreur?
• Quels sont tous les types de méthodes exposés?

Toutes ces informations sont nécessaires pour que quiconque utilise ou implémente l'API pour le besoin souhaité.

=> Regardez la série de formation Simple Postman ici.

Entretien avec Oracle PL SQL Questions et réponses

Postman fournit une méthodologie de documentation facile à utiliser et pour la documentation de base, il suffit de cliquer sur un bouton dans la collection Postman et vous pouvez obtenir une URL publique pour la documentation de votre API.

Ce que vous apprendrez:

• Création de la documentation API dans Postman
  • Caractéristiques de la documentation
  • Création de documentation
• Conclusion
  • lecture recommandée

Création de la documentation API dans Postman

Caractéristiques de la documentation

Les principales caractéristiques du générateur de documentation Postman incluent:

• Il prend en charge la syntaxe de démarque. Markdown est une syntaxe de documentation générique, que vous devriez généralement remarquer sur n'importe quel projet Github. Il permet de rendre le style et la mise en forme du texte plus familiers et plus faciles.
• Aucune syntaxe / exigences spécifiques pour la création de documentation. Les informations de demande et de collecte sont utilisées de la meilleure façon pour générer de la documentation.
• Il peut être publié sur une URL publique ou sur un domaine personnalisé (pour les utilisateurs d'entreprise).
• Génère des extraits de code pour effectuer des appels à l'API dans différents langages tels que C #, PHP, Ruby, Python, Node, etc.

Création de documentation

Le générateur de documents Postman fait référence à la collection, au dossier et à la description de la demande individuelle et les rassemble lors de la création ou de la génération de la documentation pour la collection.

Il utilise divers paramètres de requête tels que les en-têtes, les paramètres de chaîne de requête, les paramètres de formulaire et indique l'utilisation de ces valeurs dans la documentation de la requête.

Voici un didacticiel vidéo:

Créons une collection de base avec 3 requêtes en utilisant la même API de test que nos autres articles. Nous ajouterons des informations à la description de la collection ainsi qu'aux demandes individuelles et créerons également des exemples de demandes et de réponses, qui seront également capturées lors de la création de la documentation.

Suivez les étapes ci-dessous pour ajouter des informations de base sur les demandes, puis pour créer la documentation.

#1) Créez une collection avec 3 demandes, c'est-à-dire enregistrer l'utilisateur, connecter l'utilisateur et obtenir l'utilisateur (reportez-vous Ici pour les charges utiles de demande et les URL d'API).

#deux) Ajoutons maintenant des informations au format markdown à la collection. Markdown est un format standard utilisé pour presque toute la documentation de Github (pour plus d'informations sur le markdown, reportez-vous Ici ).

Nous ajouterons des informations à la description de la collection dans le format de démarque comme ci-dessous.

Pour prévisualiser à quoi ressemble le démarque, reportez-vous au portail Web open-source ici.

# 3) Nous allons maintenant ajouter les descriptions aux demandes individuelles de la collection. Semblable à la collection, le format markdown est également pris en charge pour les descriptions de demande (pour plus d'informations sur le guide markdown, reportez-vous Ici ).

Voyons un exemple de l'une des demandes de point de terminaison Register User (la même chose peut être appliquée à d'autres demandes également).

Texte de démarque:

Aperçu Markdown:

# 4) Pour tous les points de terminaison de l'API, capturons ou sauvegardons un exemple qui serait utilisé par le générateur de documentation.

Un exemple n'est rien d'autre qu'un exemple de demande-réponse pour la demande d'API en considération. L'enregistrement de la réponse comme exemple permet au générateur de documentation de la capturer en tant que partie de la documentation elle-même.

Pour enregistrer un exemple, appuyez sur le 'Envoyer' bouton pour exécuter la demande et dans l'onglet réponse, cliquez sur Enregistrer la réponse -> Enregistrer comme exemple .

Une fois que l'exemple est enregistré, il est conservé dans la collection et peut être consulté à tout moment dans le futur via un Exemples lien dans le générateur de demande.

# 5) Une fois toutes les informations ci-dessus ajoutées, voyons comment créer un aperçu de la documentation.

Ouvrez les options de collecte et cliquez sur ' Publier des documents ».

Noter: Une chose importante à noter ici est que seuls les utilisateurs enregistrés avec Postman pourront utiliser la fonction Publier des documents sur Postman. L'inscription est gratuite mais doit être effectuée via votre compte de messagerie. Il existe d'autres capacités / fonctionnalités telles que le partage de collections et d'espaces de travail, la création de moniteurs, etc., qui sont ajoutées aux comptes enregistrés.

# 6) Une fois ' Publier des documents »Est exécuté, un onglet de navigateur est ouvert avec les détails de la collection Postman (en interne, Postman héberge cette collection sur ses propres serveurs ainsi qu'en plus du système de fichiers local de l'utilisateur).

Cliquer sur 'Aperçu' pour afficher la documentation avant sa publication.

' Publier la collection »Lien publiera la documentation sur une URL accessible au public. Il n'est généralement pas recommandé de publier des API contenant des informations d'autorisation sensibles à publier sur l'URL publique. Ces API peuvent être publiées à l'aide de domaines personnalisés avec des comptes d'entreprise du facteur.

# 7) Voyons à quoi ressemble l'aperçu de la documentation. En cliquant ' Aperçu de la documentation »Ouvre la documentation dans un mode d’aperçu hébergé sur les serveurs de Postman. Voyons quels différents détails sont capturés dans la documentation (comme nous l'avons configuré à différents endroits. Par exemple , description de la collection, description de la demande et exemples).

Dans les 2 captures d'écran ci-dessus, vous pouvez voir que toutes les informations qui ont été ajoutées à la collection et les descriptions des demandes sont capturées dans un style démarqué dans l'aperçu de la documentation.

comment jouer mkv sur pc

En outre, la documentation par défaut fournit des liaisons de langue telles que mises en évidence et cela facilite beaucoup la tâche pour quelqu'un qui souhaite directement faire la demande d'API dans la langue répertoriée.

# 8) Il vous permet également d'effectuer des modifications de style très basiques comme changer la couleur d'arrière-plan, changer la couleur d'arrière-plan et de premier plan des modèles d'en-tête, etc. Mais dans l'ensemble, la vue par défaut elle-même est suffisante pour publier un très bon ensemble de documentation capturant détails importants sur l'API.

Conclusion

Dans ce didacticiel, nous avons parcouru le support de la documentation API fourni par Postman, à l'aide duquel nous pouvons créer une documentation élégante et stylée avec un minimum d'effort.

Il permet également de nombreux bons modèles et un style défini par l'utilisateur qui pourraient être appliqués aux documents générés et permet également de publier de la documentation sur une URL publique.

Pour les points de terminaison d'API privés, il existe également une disposition permettant de publier la documentation dans un domaine personnalisé qui pourrait être configuré pour les comptes ou les utilisateurs d'entreprise.

Lectures complémentaires = >> Comment publier un contrat Pact à Pact Broker

=> Visitez ici pour apprendre Postman From Scratch.

lecture recommandée

• Tutoriel POSTMAN: Test d'API avec POSTMAN
• Comment et quand utiliser les scripts de pré-demande et de post-demande Postman?
• Comment utiliser Postman pour tester différents formats d'API?
• Comment utiliser l'intégration de la ligne de commande avec Newman dans Postman?
• Tutoriel de l'API Rest: architecture et contraintes de l'API REST
• Générer une documentation vivante avec des cornichons pour les fichiers d'entités Specflow
• Automatisation de la validation des réponses avec des assertions dans Postman
• Codes de réponse de l'API Rest et types de demandes de repos