Menu

Come creare la documentazione API in Postman?

how create api documentation postman

Prova Il Nostro Strumento Per Eliminare I Problemi

Questo tutorial spiega come creare una bella documentazione con stile con sforzi minimi utilizzando il supporto per la documentazione API fornito dallo strumento Postman:

Per qualsiasi API, sia interna che pubblica, la documentazione è uno degli ingredienti più essenziali per il suo successo.

La ragione principale è che la documentazione è il modo in cui comunichi con i tuoi utenti.

  • Come dovrebbe essere utilizzata la tua API?
  • Quali sono tutti i codici di stato supportati?
  • Quali sono i codici di errore?
  • Quali sono tutti i tipi di metodo esposti?

Tutte queste informazioni sono necessarie a chiunque possa utilizzare o implementare l'API per l'esigenza desiderata.

=> Guarda qui la serie di formazione Simple Postman.

Postman - Creazione della documentazione API

miglior pulitore di sistema per Windows 10

Postman fornisce una metodologia di documentazione facile da usare e per la documentazione di base, è semplice come fare clic su un pulsante nella raccolta di Postman e puoi ottenere l'URL pubblico per la tua documentazione API.

Cosa imparerai:

Creazione della documentazione API in Postman

Caratteristiche della documentazione

Le caratteristiche salienti del generatore di documentazione di Postman includono:

  • Supporta la sintassi del markdown. Markdown è una sintassi di documentazione generica, che di solito dovresti aver notato in qualsiasi progetto Github. Permette di rendere lo stile e la formattazione del testo più familiare e semplice.
  • Nessuna sintassi / requisiti specifici per la creazione della documentazione. Le informazioni sulla richiesta e sulla raccolta vengono utilizzate nel modo migliore per generare documentazione.
  • Può essere pubblicato su un URL pubblico o su un dominio personalizzato (per utenti aziendali).
  • Genera snippet di codice per effettuare chiamate all'API in diversi linguaggi come C #, PHP, Ruby, Python, Node, ecc.

Creazione della documentazione

Il generatore di documenti Postman fa riferimento alla raccolta, alla cartella e alla descrizione della richiesta individuale e le confronta durante la creazione o la generazione della documentazione per la raccolta.

Utilizza vari parametri di richiesta come intestazioni, parametri della stringa di query, parametri del modulo e indica l'uso di questi valori nella documentazione della richiesta.

Ecco un video tutorial:

Creiamo una raccolta di base con 3 richieste utilizzando la stessa API di test degli altri nostri articoli. Aggiungeremo alcune informazioni alla descrizione della collezione e alle singole richieste e creeremo anche alcune richieste e risposte di esempio, che verranno catturate anche durante la creazione della documentazione.

Seguire i passaggi seguenti per aggiungere informazioni di base sulle richieste e quindi creare la documentazione.

# 1) Crea una raccolta con 3 richieste, ovvero Registra utente, Accedi utente e Ottieni utente (fare riferimento Qui per i payload delle richieste e gli URL API).

#Due) Ora aggiungiamo alcune informazioni in formato markdown alla raccolta. Markdown è un formato standard utilizzato per quasi tutta la documentazione in Github (per ulteriori informazioni sul markdown, fare riferimento a Qui ).

Aggiungeremo alcune informazioni alla descrizione della raccolta nel formato di ribasso come di seguito.

Descrizione della collezione in formato markdown

Per visualizzare in anteprima l'aspetto del markdown, fare riferimento al portale Web open source Qui.

Documentazione di Markdown

# 3) Ora aggiungeremo le descrizioni alle singole richieste nella raccolta. Simile alla raccolta, il formato markdown è supportato anche per le descrizioni delle richieste (per informazioni più dettagliate sulla guida markdown, fare riferimento Qui ).

Vediamo un esempio di una delle richieste per l'endpoint di registrazione dell'utente (lo stesso può essere applicato anche ad altre richieste).

Markdown Text:

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

Anteprima Markdown:

Anteprima Markdown

# 4) Per tutti gli endpoint API, acquisiamo o salviamo un esempio che verrebbe utilizzato dal generatore di documentazione.

Un esempio non è altro che un esempio di richiesta-risposta per la richiesta API in considerazione. Il salvataggio della risposta come esempio consente al generatore di documentazione di catturarla come parte della documentazione stessa.

Per salvare un esempio, premi il pulsante 'Spedire' per eseguire la richiesta e nella scheda risposta, fare clic su Salva risposta -> Salva come esempio .

Salva esempio

Una volta salvato, l'esempio viene mantenuto nella raccolta ed è possibile accedervi in ​​qualsiasi momento in futuro tramite un file Esempi link nel generatore di richieste.

# 5) Una volta aggiunte tutte le informazioni di cui sopra, vediamo come creare un'anteprima della documentazione.

Apri le opzioni di raccolta e fai clic su ' Pubblica documenti '.

Pubblica documenti

Nota: Una cosa importante da notare qui è che solo gli utenti registrati con Postman potranno utilizzare la funzione Pubblica documenti su Postman. La registrazione è gratuita ma deve essere effettuata tramite il tuo account di posta elettronica. Ci sono altre capacità / caratteristiche come la condivisione di raccolte e spazi di lavoro, la creazione di monitor, ecc., Che vengono aggiunti agli account registrati.

# 6) Una volta ' Pubblica documenti 'Viene eseguito, viene aperta una scheda del browser con i dettagli della raccolta di Postman (internamente Postman ospita questa raccolta anche sui propri server oltre al file system locale dell'utente).

Raccolta della documentazione

Clicca su 'Anteprima' per visualizzare la documentazione prima che venga pubblicata.

' Pubblica raccolta 'Pubblicherà la documentazione su un URL accessibile pubblicamente. In genere non è consigliabile pubblicare API con informazioni di autorizzazione sensibili da pubblicare nell'URL pubblico. Tali API possono essere pubblicate utilizzando domini personalizzati con account aziendali del postino.

# 7) Vediamo come appare l'anteprima della documentazione. Facendo clic su ' Documentazione in anteprima 'Apre la documentazione in una modalità di anteprima ospitata sui server di Postman. Vediamo quali diversi dettagli vengono catturati nella documentazione (come abbiamo configurato in luoghi diversi. Per esempio , descrizione della collezione, descrizione della richiesta ed esempi).

Esempio di documentazione del postino

Richiedi descrizione in Markdown

Nelle due schermate precedenti, puoi vedere che tutte le informazioni che sono state aggiunte alla raccolta e le descrizioni delle richieste vengono catturate in modo markdown nell'anteprima della documentazione.

crea un array di stringhe java

Inoltre, la documentazione per impostazione predefinita fornisce i collegamenti della lingua come evidenziato e ciò rende molto più semplice per qualcuno che desidera effettuare direttamente la richiesta API nella lingua elencata.

# 8) Consente inoltre di eseguire modifiche di stile molto basilari come cambiare il colore di sfondo, cambiare il colore di sfondo e primo piano dei modelli di intestazione, ecc. dettagli importanti sull'API.

Conclusione

In questo tutorial, abbiamo esaminato il supporto della documentazione API fornito da Postman, utilizzando il quale possiamo creare una documentazione di bell'aspetto e con stile con il minimo sforzo.

Consente inoltre molti buoni modelli e stili definiti dall'utente che potrebbero essere applicati ai documenti generati e consente anche di pubblicare la documentazione su un URL pubblico.

Per gli endpoint API privati, esiste anche una disposizione per pubblicare la documentazione in un dominio personalizzato che potrebbe essere configurato per gli account o gli utenti aziendali.

Ulteriore lettura = >> Come pubblicare il Pact Contract al Pact Broker

=> Visita qui per imparare Postman From Scratch.

Lettura consigliata

^