Hur skapar man API-dokumentation i brevbäraren?

how create api documentation postman

Denna handledning förklarar hur man skapar snygg, utformad dokumentation med minimala ansträngningar med API-dokumentationsstöd som tillhandahålls av Postman Tool:

För alla API: er, internt eller offentligt, är dokumentation en av de viktigaste ingredienserna för dess framgång.

Den främsta anledningen till detta är att dokumentation är hur du kommunicerar med dina användare.

• Hur ska ditt API användas?
• Vad stöds alla statuskoder?
• Vilka är felkoderna?
• Vad exponeras för alla metodtyper?

All denna information är nödvändig för vem som helst att använda eller implementera API för önskat behov.

=> Se upp den enkla postbilsutbildningen här.

bästa marknadsundersökningsföretag att arbeta för

Postman tillhandahåller en lättanvänd dokumentationsmetodik och för grundläggande dokumentation är det så enkelt som att klicka på en knapp genom Postman-samlingen och du kan få en offentlig URL för din API-dokumentation.

Vad du kommer att lära dig:

• Skapa API-dokumentation i brevbäraren
  • Dokumentationsfunktioner
  • Skapa dokumentation
• Slutsats
  • Rekommenderad läsning

Skapa API-dokumentation i brevbäraren

Dokumentationsfunktioner

De framträdande funktionerna i Postman-dokumentationsgeneratorn inkluderar:

• Den stöder markdown-syntax. Markdown är generisk dokumentationssyntax som du vanligtvis har lagt märke till i alla Github-projekt. Det gör att styling och textformatering blir mer bekant och enklare.
• Ingen specifik syntax / krav för att skapa dokumentation. Begäran och insamlingsinfo används på bästa sätt för att generera dokumentation.
• Den kan publiceras på en offentlig URL eller till en anpassad domän (för företagsanvändare).
• Skapar kodavsnitt för att ringa till API: et på olika språk som C #, PHP, Ruby, Python, Node, etc.

Skapa dokumentation

Postman-dokumentgeneratorn hänvisar till samlingen, mappen och beskrivningen av enskild begäran och samlar dem medan du skapar eller genererar dokumentation för samlingen.

Den använder olika förfrågningsparametrar som rubriker, frågesträngsparametrar, formulärparametrar och anger användningen av dessa värden i begärandedokumentationen.

Här är en videohandledning:

Låt oss skapa en grundläggande samling med tre förfrågningar med samma test-API som våra andra artiklar. Vi kommer att lägga till lite information i samlingsbeskrivningen såväl som till de enskilda förfrågningarna och också skapa några exempelförfrågningar och svar, som också kommer att fångas när dokumentationen skapas.

Följ stegen nedan för att lägga till grundläggande information om förfrågningarna och sedan skapa dokumentationen.

# 1) Skapa en samling med tre förfrågningar, dvs. registrera användare, inloggningsanvändare och få användare (se här för begäran nyttolaster och API-URL: er).

#två) Låt oss nu lägga till lite information i markdown-format till samlingen. Markdown är ett standardformat som används för nästan all dokumentation i Github (för mer information om markdown se här ).

Vi lägger till lite information i samlingsbeskrivningen i markdown-format enligt nedan.

För att förhandsgranska hur markdown ser ut, se webbportalen med öppen källkod här.

# 3) Nu lägger vi till beskrivningarna till enskilda förfrågningar i samlingen. I likhet med samlingen stöds markdown-formatet även för förfrågningsbeskrivningar (för mer detaljerad information om markdown-guiden, se här ).

Låt oss se ett exempel på en av förfrågningarna för slutanvändarregister för användare (Detsamma kan också tillämpas på andra förfrågningar).

Markdown Text:

Förhandsgranskning av markdown:

# 4) För alla API-slutpunkter, låt oss fånga eller spara ett exempel som skulle användas av dokumentationsgeneratorn.

Ett exempel är inget annat än ett exempel på begäran-svar för API-begäran i beaktande. Att spara svaret som ett exempel gör det möjligt för dokumentationsgeneratorn att fånga det som en del av själva dokumentationen.

För att spara ett exempel, tryck på 'Skicka' för att utföra begäran och klicka på fliken Svar Spara svar -> Spara som exempel .

När exemplet har sparats blir det kvar i samlingen och kan nås när som helst i framtiden via en Exempel länk i begäran byggare.

# 5) När all ovanstående information har lagts till kan vi se hur du skapar en förhandsgranskning av dokumentation.

Öppna samlingsalternativen och klicka på “ Publicera dokument ”.

Notera: En viktig sak att notera här är att endast registrerade användare med Postman kan använda Publicera dokumentfunktionen på Postman. Registreringen är gratis men måste göras via ditt e-postkonto. Det finns andra funktioner / funktioner som att dela samlingar och arbetsytor, skapa bildskärmar etc. som läggs till de registrerade kontona.

# 6) En gång ' Publicera dokument ”Exekveras, öppnas en webbläsarflik med Postmans samlingsdetaljer (internt är Postman värd för denna samling till sina egna servrar förutom användarens lokala filsystem).

Klicka på 'Förhandsvisning' för att se dokumentationen innan den publiceras.

' Publicera samling ”-Länken publicerar dokumentationen till en offentligt tillgänglig URL. Det rekommenderas vanligtvis inte att publicera API: er som har känslig auktoriseringsinformation för att publicera till den offentliga URL: n. Sådana API: er kan publiceras med anpassade domäner med företagskonton för Postman.

# 7) Låt oss se hur dokumentförhandsgranskningen ser ut. Klicka på “ Förhandsgranska dokumentation ”Öppnar dokumentationen i ett förhandsgranskningsläge som finns på Postmans servrar. Låt oss se vilka olika detaljer som finns i dokumentationen (som vi konfigurerade på olika platser. Till exempel , samlingsbeskrivning, begäran beskrivning och exempel).

I ovanstående två skärmdumpar kan du se att all information som har lagts till i samlingen och förfrågningsbeskrivningar fångas på ett markdownformat sätt i dokumentförhandsgranskningen.

bästa gratis Windows 10 underhållsprogramvara

Dokumentationen innehåller också som standard språkbindningar som markerade och det gör det mycket lättare för någon som direkt vill göra API-begäran på det listade språket.

# 8) Det låter dig också utföra mycket grundläggande stylingsändringar som att ändra bakgrundsfärgen, ändra bakgrunds- och förgrundsfärgen på rubrikmallarna etc. Men totalt sett är standardvyn i sig tillräcklig för att publicera en riktigt bra dokumentation som fångar mycket viktiga detaljer om API: et.

Slutsats

I den här guiden gick vi igenom API-dokumentationsstödet som tillhandahålls av Postman, med vilket vi kan skapa en snygg, utformad dokumentation med minimal ansträngning.

Det tillåter också många bra mallar och användardefinierad styling som kan tillämpas på de genererade dokumenten och tillåter publicering av dokumentation till en offentlig URL också.

För privata API-slutpunkter finns det också en möjlighet att publicera dokumentation till en anpassad domän som kan konfigureras för företagskonton eller användare.

Ytterligare läsning = >> Hur man publicerar paktkontrakt till paktsmäklare

=> Besök här för att lära dig brevbäraren från grunden.

Rekommenderad läsning

• POSTMAN-handledning: API-testning med POSTMAN
• Hur & när ska man använda Postman Pre Request och Post Request Scripts?
• Hur använder jag Postman för att testa olika API-format?
• Hur man använder kommandoradsintegration med Newman i brevbäraren?
• Rest API Tutorial: REST API Architecture And Constraints
• Skapa levande dokumentation med pickles för specflow-funktionsfiler
• Automatisera svarsvalidering med påståenden i brevbäraren
• Rest API-svarskoder och typer av vilovärden