Menu

Sådan oprettes API-dokumentation i postbud?

how create api documentation postman

Prøv Vores Instrument Til At Fjerne Problemer

Denne vejledning forklarer, hvordan man opretter flot, formet dokumentation med minimal indsats ved hjælp af API-dokumentationsstøtte leveret af Postman Tool:

For enhver API, hvad enten det er internt eller offentligt, er dokumentation en af ​​de mest vigtige ingredienser for dens succes.

Hovedårsagen til det er, at dokumentation er den måde, du kommunikerer med dine brugere på.

  • Hvordan din API skal bruges?
  • Hvad understøttes alle statuskoder?
  • Hvad er fejlkoderne?
  • Hvad er alle metodetyper udsat for?

Al denne information er nødvendig for enhver at bruge eller implementere API til det ønskede behov.

=> Hold øje med den enkle postbudstræningsserie her.

Postbud - Oprettelse af API-dokumentation

hvordan man ripper dvd gratis

Postman giver en brugervenlig dokumentationsmetode og til grundlæggende dokumentation er det så simpelt som at klikke på en knap gennem Postman-samlingen, og du kan få offentlig URL til din API-dokumentation.

Hvad du vil lære:

Oprettelse af API-dokumentation i postbud

Dokumentationsfunktioner

De fremtrædende funktioner i Postman dokumentationsgenerator inkluderer:

  • Det understøtter markdown-syntaks. Markdown er generisk dokumentationssyntaks, som du normalt har bemærket i ethvert Github-projekt. Det gør det muligt at gøre styling og tekstformatering mere kendt og lettere.
  • Ingen specifik syntaks / krav til oprettelse af dokumentation. Forespørgsel og indsamlingsinfo bruges på den bedste måde til at generere dokumentation.
  • Det kan offentliggøres til en offentlig URL eller til et brugerdefineret domæne (for virksomhedsbrugere).
  • Genererer kodestykker til opkald til API på forskellige sprog som C #, PHP, Ruby, Python, Node osv.

Oprettelse af dokumentation

Postbanks dokumentgenerator henviser til samlingen, mappen og den individuelle anmodningsbeskrivelse og samler dem, mens de opretter eller genererer dokumentation til samlingen.

Det gør brug af forskellige anmodningsparametre som overskrifter, forespørgselsstrengparametre, formularparametre og angiver brugen af ​​disse værdier i anmodningsdokumentationen.

Her er en videotutorial:

Lad os oprette en grundlæggende samling med 3 anmodninger ved hjælp af den samme test-API som vores andre artikler. Vi vil tilføje nogle oplysninger til samlingsbeskrivelsen såvel som til de enkelte anmodninger og også oprette nogle eksempler på anmodninger og svar, som også vil blive fanget under oprettelsen af ​​dokumentationen.

Følg nedenstående trin for at tilføje grundlæggende info om anmodningerne og derefter oprette dokumentationen.

# 1) Opret en samling med 3 anmodninger, dvs. Registrer bruger, Login bruger og Få bruger (Se her for anmodning om nyttelast og API-URL'er).

#to) Lad os nu tilføje nogle oplysninger i markdown-format til samlingen. Markdown er et standardformat, der bruges til næsten al dokumentation i Github (For mere information om markdown henvises til her ).

Vi tilføjer nogle oplysninger til samlingsbeskrivelsen i markdown-format som nedenfor.

Samlingsbeskrivelse i markdown-format

For at få vist, hvordan markdown ser ud, henvises til open source-webportalen her.

Markdown-dokumentation

# 3) Nu vil vi tilføje beskrivelserne til individuelle anmodninger i samlingen. I lighed med samlingen understøttes markdown-formatet også for anmodningsbeskrivelser (For mere detaljerede oplysninger om markdown guide, se her ).

Lad os se et eksempel på en af ​​anmodningerne om registerbrugerendepunkt (Det samme kan også anvendes på andre anmodninger).

Markdown-tekst:

API endpoint to *Register* a user in the system. > A successful registration will result in a *HTTP 200* Status code

Eksempel på markdown:

Eksempel på markdown

# 4) Lad os fange eller gemme et eksempel, der bruges af dokumentationsgeneratoren, for alle API-slutpunkter.

Et eksempel er intet andet end et eksempel på anmodning-svar til API-anmodningen i betragtning. Hvis du gemmer svaret som et eksempel, kan dokumentationsgeneratoren fange det som en del af selve dokumentationen.

For at gemme et eksempel skal du trykke på 'Sende' knappen for at udføre anmodningen, og klik på fanen svar Gem svar -> Gem som eksempel .

Gem eksempel

Når eksemplet er gemt, bliver det vedvarende i samlingen og kan tilgås når som helst i fremtiden via en Eksempler link i anmodningsbyggeren.

# 5) Når alle ovenstående oplysninger er tilføjet, skal vi se, hvordan du opretter en forhåndsvisning af dokumentation.

Åbn opsamlingsmulighederne, og klik på “ Udgiv Docs ”.

Udgiv Docs

Bemærk: En vigtig ting at bemærke her er, at kun registrerede brugere med Postman kan bruge funktionen Publish docs på Postman. Registreringen er gratis, men skal ske via din e-mail-konto. Der er andre funktioner / funktioner som deling af samlinger og arbejdsområder, oprettelse af skærme osv., Der føjes til de registrerede konti.

# 6) Enkelt gang ' Udgiv Docs ”Udføres, åbnes en browserfane med Postman-samlingsoplysningerne (internt er Postman vært for denne samling på deres egne servere ud over brugerens lokale filsystem).

Dokumentationssamling

Klik på 'Preview' for at se dokumentationen, før den offentliggøres.

' Udgiv samling ”Link vil offentliggøre dokumentationen til en offentligt tilgængelig URL. Det anbefales generelt ikke at offentliggøre API'er, der har følsomme autorisationsoplysninger til offentliggørelse til den offentlige URL. Sådanne API'er kan udgives ved hjælp af brugerdefinerede domæner med Postmands virksomhedskonti.

# 7) Lad os se, hvordan dokumentationseksemplet ser ud. Klik på “ Eksempel på dokumentation ”Åbner dokumentationen i en preview-tilstand, der er hostet på Postmans servere. Lad os se, hvilke forskellige detaljer der er fanget i dokumentationen (som vi konfigurerede forskellige steder. For eksempel , samlingsbeskrivelse, anmodningsbeskrivelse og eksempler).

Dokumentationseksempel på postbud

Anmod om beskrivelse i Markdown

I de ovennævnte 2 skærmbilleder kan du se, at alle de oplysninger, der blev føjet til samlingen og anmodningsbeskrivelser, er fanget på en markdown-stilet måde i dokumentationseksemplet.

bedste gratis sikkerhedskopieringssoftware til mac

Dokumentationen indeholder også som standard sprogbindinger som fremhævet, og det gør det meget lettere for nogen, der direkte ønsker at fremsætte API-anmodningen på det anførte sprog.

# 8) Det giver dig også mulighed for at udføre meget grundlæggende stylingændringer som at ændre baggrundsfarven, ændre baggrunds- og forgrundsfarven på headerskabeloner osv. Men samlet set er standardvisningen i sig selv tilstrækkelig til at udgive et rigtig godt sæt dokumentation, der fanger en masse vigtige detaljer om API.

Konklusion

I denne vejledning gik vi gennem API-dokumentationsstøtten leveret af Postman, ved hjælp af hvilken vi kan skabe en flot, stylet dokumentation med minimal indsats.

Det tillader også masser af gode skabeloner og brugerdefineret styling, der kan anvendes på de genererede dokumenter og tillader også offentliggørelse af dokumentation til en offentlig URL.

For private API-slutpunkter er der også en bestemmelse om at offentliggøre dokumentation til et brugerdefineret domæne, der kan konfigureres til virksomhedskonti eller brugere.

Yderligere læsning = >> Sådan offentliggøres pagtkontrakt til pagtmægler

=> Besøg her for at lære postbud fra bunden.

Anbefalet læsning

^