Hvordan lage API-dokumentasjon i postbud?

how create api documentation postman

Denne opplæringen forklarer hvordan du lager god, stilig dokumentasjon med minimal innsats ved hjelp av API-dokumentasjonsstøtte levert av Postman Tool:

For ethvert API, enten det er internt eller offentlig, er dokumentasjon en av de viktigste ingrediensene for suksessen.

Hovedårsaken til det er at dokumentasjon er måten du kommuniserer med brukerne dine.

• Hvordan API-et ditt skal brukes?
• Hva støttes alle statuskoder?
• Hva er feilkodene?
• Hva blir alle metodetyper utsatt for?

All denne informasjonen er nødvendig for alle å bruke eller implementere API for ønsket behov.

=> Se opp The Simple Postman Training Series her.

sirkulær matrix kø c ++

Postman gir en brukervennlig dokumentasjonsmetodikk, og for grunnleggende dokumentasjon er det så enkelt som å klikke på en knapp gjennom Postman-samlingen, og du kan få offentlig URL til API-dokumentasjonen.

Hva du vil lære:

• Opprette API-dokumentasjon i Postman
  • Dokumentasjonsfunksjoner
  • Opprette dokumentasjon
• Konklusjon
  • Anbefalt lesing

Opprette API-dokumentasjon i Postman

Dokumentasjonsfunksjoner

De fremtredende funksjonene til Postman dokumentasjonsgenerator inkluderer:

• Den støtter markdown-syntaksen. Markdown er generell dokumentasjonssyntaks, som du vanligvis burde ha lagt merke til i ethvert Github-prosjekt. Det gjør det mulig å gjøre styling og tekstformatering mer kjent og enklere.
• Ingen spesifikke syntaks / krav for å lage dokumentasjon. Forespørsel og innsamlingsinfo brukes på den beste måten å generere dokumentasjon.
• Den kan publiseres til en offentlig URL eller til et tilpasset domene (for bedriftsbrukere).
• Genererer kodebiter for å ringe til API på forskjellige språk som C #, PHP, Ruby, Python, Node, etc.

Opprette dokumentasjon

Postman dokumentgenerator refererer til samlingen, mappen og beskrivelsen av den enkelte forespørselen og samler dem mens du oppretter eller genererer dokumentasjon for samlingen.

Den bruker forskjellige forespørselsparametere som overskrifter, spørringsstrengparametere, skjemaparametere og indikerer bruken av disse verdiene i forespørselsdokumentasjonen.

Her er en videoopplæring:

La oss lage en grunnleggende samling med 3 forespørsler som bruker samme test-API som de andre artiklene våre. Vi vil legge til litt informasjon i samlingsbeskrivelsen så vel som til de enkelte forespørslene, og også lage noen eksempler på forespørsler og svar, som også blir fanget mens du lager dokumentasjonen.

Følg trinnene nedenfor for å legge til grunnleggende informasjon om forespørslene og deretter opprette dokumentasjonen.

#1) Opprett en samling med 3 forespørsler, dvs. registrer bruker, påloggingsbruker og få bruker (se her for forespørsel om nyttelast og API-URLer).

#to) La oss nå legge til litt informasjon i markdown-format i samlingen. Markdown er et standardformat som brukes til nesten all dokumentasjon i Github (For mer informasjon om markdown, se her ).

Vi legger til litt informasjon i samlingsbeskrivelsen i markdown-format som nedenfor.

For å forhåndsvise hvordan markdown ser ut, se nettportalen med åpen kildekode her.

# 3) Nå vil vi legge til beskrivelsene til individuelle forespørsler i samlingen. I likhet med samlingen støttes markdown-formatet også for forespørselsbeskrivelser (For mer detaljert informasjon om markdown guide, se her ).

La oss se et utvalg av en av forespørslene for Registrer bruker-endepunkt (Det samme kan også brukes på andre forespørsler).

Markdown Tekst:

Forhåndsvisning av Markdown:

# 4) For alle API-endepunktene, la oss fange eller lagre et eksempel som brukes av dokumentasjonsgeneratoren.

Et eksempel er ingenting annet enn et eksempel på svar fra API-forespørselen. Hvis du lagrer svaret som et eksempel, kan dokumentasjonsgeneratoren fange den som en del av selve dokumentasjonen.

For å lagre et eksempel, trykk på 'Sende' knappen for å utføre forespørselen, og klikk på svarfanen Lagre svar -> Lagre som eksempel .

Når eksemplet er lagret, blir det vedvarende i samlingen og kan nås når som helst i fremtiden gjennom en Eksempler lenke i forespørselsbyggeren.

# 5) Når all informasjonen ovenfor er lagt til, kan vi se hvordan du lager en forhåndsvisning av dokumentasjon.

Åpne samlingsalternativene og klikk “ Publiser Dokumenter ”.

Merk: En viktig ting å merke seg her er at bare registrerte brukere med Postman kan bruke Publish docs-funksjonen på Postman. Registreringen er gratis, men må gjøres via e-postkontoen din. Det er andre funksjoner / funksjoner som deling av samlinger og arbeidsområder, oppretting av skjermer osv. Som blir lagt til de registrerte kontoene.

# 6) En gang ' Publiser Dokumenter ”Utføres, åpnes en nettleserfane med Postman-samlingsdetaljene (internt er Postman vert for denne samlingen til sine egne servere, i tillegg til brukerens lokale filsystem).

Klikk på “Forhåndsvisning” for å se dokumentasjonen før den blir publisert.

' Publiser samling ”-Linken vil publisere dokumentasjonen til en offentlig tilgjengelig URL. Det anbefales generelt ikke å publisere API-er som har sensitiv autorisasjonsinformasjon for å publisere til den offentlige URL-en. Slike API-er kan publiseres ved hjelp av egendefinerte domener med Postman-virksomhetskontoer.

# 7) La oss se hvordan forhåndsvisning av dokumentasjonen ser ut. Klikk på “ Forhåndsvisning av dokumentasjon ”Åpner dokumentasjonen i en forhåndsvisningsmodus som er vert på Postmans servere. La oss se hvilke forskjellige detaljer som er fanget i dokumentasjonen (som vi konfigurerte forskjellige steder. For eksempel , samlingsbeskrivelse, forespørselsbeskrivelse og eksempler).

I de ovennevnte to skjermbildene kan du se at all informasjonen som ble lagt til samlingen og forespørselsbeskrivelsene blir fanget på en markdown-stil i forhåndsvisningen av dokumentasjonen.

beste programvare for kloning av stasjoner windows 10

Dokumentasjonen gir også som standard språkbindinger som uthevet, og det gjør det mye enklere for noen som ønsker å direkte gjøre API-forespørselen på det oppførte språket.

# 8) Den lar deg også utføre veldig grunnleggende stylingmodifikasjoner som å endre bakgrunnsfargen, endre bakgrunns- og forgrunnsfargen på toppmalene osv. Men generelt er standardvisningen i seg selv tilstrekkelig til å publisere et veldig godt sett med dokumentasjon som fanger mye viktige detaljer om API.

Konklusjon

I denne veiledningen gikk vi gjennom API-dokumentasjonsstøtten levert av Postman, ved hjelp av hvilken vi kan lage en pen, stilig dokumentasjon med minimal innsats.

Det tillater også mange gode maler og brukerdefinert styling som kan brukes på de genererte dokumentene, og tillater publisering av dokumentasjon til en offentlig URL også.

For private API-endepunkter er det også en bestemmelse om å publisere dokumentasjon til et tilpasset domene som kan konfigureres for bedriftskontoer eller brukere.

Videre lesing = >> Hvordan publiserte Pact Contract to Pact Broker

=> Besøk her for å lære postbud fra grunnen.

Anbefalt lesing

• POSTMAN-veiledning: API-testing ved hjelp av POSTMAN
• Hvordan og når skal jeg bruke manuskript for forhåndsforespørsel og postforespørsel?
• Hvordan bruke Postman til å teste forskjellige API-formater?
• Hvordan bruke kommandolinjeintegrasjon med Newman In Postman?
• Rest API Tutorial: REST API Architecture And Constraints
• Generer levende dokumentasjon med pickles for specflow-funksjonsfiler
• Automatisering av svarvalidering med påstander i postbud
• Rest API-responskoder og typer hvileforespørsler