how create api documentation postman
In deze zelfstudie wordt uitgelegd hoe u met minimale inspanningen goed uitziende, stijlvolle documentatie kunt maken met behulp van de API-documentatieondersteuning van Postman Tool:
Voor elke API, of deze nu intern of openbaar is, is documentatie een van de meest essentiële ingrediënten voor het succes ervan.
De belangrijkste reden hiervoor is dat documentatie de manier is waarop u met uw gebruikers communiceert.
- Hoe uw API moet worden gebruikt?
- Welke statuscodes worden ondersteund?
- Wat zijn de foutcodes?
- Welke soorten methoden worden weergegeven?
Al deze informatie is nodig voor iedereen om de API te gebruiken of te implementeren voor de gewenste behoefte.
Bekijk hier de eenvoudige trainingsserie voor postbode.
hoe makefile c ++ te maken
Postman biedt een eenvoudig te gebruiken documentatiemethodologie en voor basisdocumentatie is het zo simpel als het klikken op een knop door de Postman-collectie en u kunt een openbare URL voor uw API-documentatie krijgen.
Wat je leert:
API-documentatie maken in Postman
Documentatiefuncties
De meest opvallende kenmerken van de Postman-documentatiegenerator zijn:
- Het ondersteunt markdown-syntaxis. Markdown is een generieke documentatiesyntaxis, die u normaal gesproken zou moeten opvallen bij elk Github-project. Het maakt styling en tekstopmaak vertrouwd en gemakkelijker.
- Geen specifieke syntaxis / vereisten voor het maken van documentatie. De aanvraag- en collectie-informatie wordt op de beste manier gebruikt om documentatie te genereren.
- Het kan worden gepubliceerd naar een openbare URL of naar een aangepast domein (voor zakelijke gebruikers).
- Genereert codefragmenten voor het aanroepen van de API in verschillende talen zoals C #, PHP, Ruby, Python, Node, enz.
Documentatie maken
De Postman-documentgenerator verwijst naar de collectie, map en individuele aanvraagbeschrijving en verzamelt deze tijdens het creëren of genereren van documentatie voor de collectie.
Het maakt gebruik van verschillende verzoekparameters zoals Headers, Query string-parameters, Form-parameters en geeft het gebruik van deze waarden aan in de aanvraagdocumentatie.
Hier is een video-tutorial:
Laten we een basiscollectie maken met drie verzoeken met dezelfde test-API als onze andere artikelen. We zullen wat informatie toevoegen aan de collectiebeschrijving en aan de individuele verzoeken en ook enkele voorbeeldverzoeken en antwoorden maken, die ook zullen worden vastgelegd tijdens het maken van de documentatie.
Volg de onderstaande stappen om basisinformatie over de verzoeken toe te voegen en vervolgens de documentatie te maken.
# 1) Creëer een collectie met 3 verzoeken, d.w.z. Registreer gebruiker, Login gebruiker en Get User (Verwijs hier voor payloads van verzoeken en API-URL's).
#twee) Laten we nu wat informatie in markdown-indeling aan de verzameling toevoegen. Markdown is een standaardformaat dat wordt gebruikt voor bijna alle documentatie in Github (zie voor meer informatie over markdown hier
We voegen wat informatie toe aan de collectiebeschrijving in de markdown-indeling zoals hieronder.
Raadpleeg de open-source webportal om een voorbeeld te zien van hoe de prijsverlaging eruitziet hier.
# 3) Nu zullen we de beschrijvingen toevoegen aan individuele verzoeken in de collectie. Net als bij de collectie, wordt het prijsverlagingsformaat ook ondersteund voor beschrijvingen van verzoeken (voor meer gedetailleerde informatie over de prijsverlagingsgids, zie hier
Laten we eens kijken naar een voorbeeld van een van de verzoeken voor het eindpunt van gebruiker registreren (hetzelfde kan ook worden toegepast op andere verzoeken).
Markdown-tekst:
Markdown-voorbeeld:
# 4) Laten we voor alle API-eindpunten een voorbeeld vastleggen of opslaan dat door de documentatiegenerator zou worden gebruikt.
Een voorbeeld is niets anders dan een voorbeeldverzoek-reactie voor het in overweging genomen API-verzoek. Door het antwoord op te slaan als voorbeeld, kan de documentatiegenerator het vastleggen als een onderdeel van de documentatie zelf.
Om een voorbeeld op te slaan, drukt u op de 'Sturen' om het verzoek uit te voeren en klik op het tabblad Antwoord op Antwoord opslaan -> Opslaan als voorbeeld
Nadat het voorbeeld is opgeslagen, wordt het bewaard in de verzameling en is het op elk moment in de toekomst toegankelijk via een Voorbeelden link in de aanvraagbouwer.
# 5) Zodra alle bovenstaande informatie is toegevoegd, gaan we kijken hoe we een documentatievoorbeeld kunnen maken.
Open de collectie-opties en klik op ' Publiceer documenten
Notitie: Een belangrijk punt om op te merken is dat alleen geregistreerde gebruikers van Postman de functie Documenten publiceren op Postman kunnen gebruiken. De registratie is gratis, maar moet worden gedaan via uw e-mailaccount. Er zijn andere mogelijkheden / functies, zoals het delen van verzamelingen en werkruimten, het maken van monitoren, enz., Die worden toegevoegd aan de geregistreerde accounts.
# 6) Een keer ' Publiceer documenten ”Wordt uitgevoerd, wordt een browsertabblad geopend met de gegevens van de Postman-collectie (intern host Postman deze collectie ook op hun eigen servers naast het lokale bestandssysteem van de gebruiker).
Klik op 'Voorbeeld' om de documentatie te bekijken voordat deze wordt gepubliceerd.
Collectie publiceren ”Link publiceert de documentatie naar een openbaar toegankelijke URL. Het wordt over het algemeen niet aanbevolen om API's te publiceren met gevoelige autorisatiegegevens om te publiceren naar de openbare URL. Dergelijke API's kunnen worden gepubliceerd met behulp van aangepaste domeinen met bedrijfsaccounts van de postbode.
# 7) Laten we eens kijken hoe het documentatievoorbeeld eruitziet. Klikken op ' Voorbeeld van documentatie ”Opent de documentatie in een voorbeeldmodus die wordt gehost op de servers van Postman. Laten we eens kijken welke verschillende details zijn vastgelegd in de documentatie (zoals we op verschillende plaatsen hebben geconfigureerd. Bijvoorbeeld , collectiebeschrijving, aanvraagbeschrijving en voorbeelden).
In de bovenstaande 2 schermafbeeldingen kunt u zien dat alle informatie die aan de collectie is toegevoegd en beschrijvingen van verzoeken zijn vastgelegd op een markdown-stijl in het documentatievoorbeeld.
beste website om anime online te bekijken
Ook biedt de documentatie standaard taalbindingen zoals gemarkeerd en dat maakt het een stuk eenvoudiger voor iemand die het API-verzoek rechtstreeks in de vermelde taal wil doen.
# 8) Het stelt je ook in staat om zeer eenvoudige stijlwijzigingen uit te voeren, zoals het veranderen van de achtergrondkleur, het veranderen van de achtergrond- en voorgrondkleur van de header-sjablonen, enz. Maar over het algemeen is de standaardweergave zelf voldoende om een echt goede set documentatie te publiceren waarin veel belangrijke details over de API.
Gevolgtrekking
In deze tutorial hebben we de API-documentatieondersteuning van Postman doorlopen, waarmee we met minimale inspanning een goed uitziende, opgemaakte documentatie kunnen maken.
Het maakt ook veel goede sjablonen en door de gebruiker gedefinieerde stijlen mogelijk die kunnen worden toegepast op de gegenereerde documenten en maakt het ook mogelijk om documentatie op een openbare URL te publiceren.
Voor privé API-eindpunten is er ook een voorziening om documentatie te publiceren naar een aangepast domein dat kan worden geconfigureerd voor de bedrijfsaccounts of gebruikers.
Verder lezen = >> Hoe een pactcontract naar pactmakelaar te publiceren
Bezoek hier om Postman From Scratch te leren.
Aanbevolen literatuur
- POSTMAN-zelfstudie: API-testen met POSTMAN
- Hoe en wanneer gebruik ik Postman Pre Request en Post Request Scripts?
- Hoe Postman te gebruiken voor het testen van verschillende API-indelingen?
- Hoe gebruik je opdrachtregelintegratie met Newman in Postman?
- Rest API-zelfstudie: REST API-architectuur en beperkingen
- Genereer levende documentatie met augurken voor Specflow-functiebestanden
- Automatisering van responsvalidatie met beweringen in Postman
- Rest API-antwoordcodes en soorten rustverzoeken