Μενού

Πώς να δημιουργήσετε τεκμηρίωση API στον Ταχυδρόμο;

  • Κύριος
  • Αλλα
  • Πώς να δημιουργήσετε τεκμηρίωση API στον Ταχυδρόμο;

how create api documentation postman

Δοκιμάστε Το Όργανο Μας Για Την Εξάλειψη Των Προβλημάτων

Αυτό το σεμινάριο εξηγεί πώς να δημιουργήσετε όμορφη εμφάνιση, στυλ τεκμηρίωσης με ελάχιστες προσπάθειες χρησιμοποιώντας την υποστήριξη τεκμηρίωσης API που παρέχεται από το εργαλείο Postman:

Για οποιοδήποτε API, εσωτερικό ή δημόσιο, η τεκμηρίωση είναι ένα από τα πιο απαραίτητα συστατικά για την επιτυχία του.

Ο πρωταρχικός λόγος είναι ότι η τεκμηρίωση είναι ο τρόπος με τον οποίο επικοινωνείτε με τους χρήστες σας.

  • Πώς πρέπει να χρησιμοποιείται το API σας;
  • Τι υποστηρίζονται όλοι οι κωδικοί κατάστασης;
  • Ποιοι είναι οι κωδικοί σφάλματος;
  • Ποιοι όλοι οι τύποι μεθόδων εκτίθενται;

Όλες αυτές οι πληροφορίες είναι απαραίτητες για οποιονδήποτε να χρησιμοποιήσει ή να εφαρμόσει το API για την επιθυμητή ανάγκη.

=> Παρακολουθήστε τη σειρά απλών ταχυδρόμων Postman εδώ.

Ταχυδρόμος - Δημιουργία τεκμηρίωσης API

εργαλεία δοκιμής ανοιχτού κώδικα cross browser

Ο Ταχυδρόμος παρέχει μια εύχρηστη μεθοδολογία τεκμηρίωσης και για βασική τεκμηρίωση, είναι τόσο απλό όσο κάνοντας κλικ σε ένα κουμπί μέσω της συλλογής Ταχυδρόμων και μπορείτε να λάβετε δημόσια διεύθυνση URL για την τεκμηρίωση API.

Τι θα μάθετε:

Δημιουργία τεκμηρίωσης API στον Ταχυδρόμο

Χαρακτηριστικά τεκμηρίωσης

Τα εμφανή χαρακτηριστικά της γεννήτριας τεκμηρίωσης Postman περιλαμβάνουν:

  • Υποστηρίζει σύνταξη markdown. Το Markdown είναι μια γενική σύνταξη τεκμηρίωσης, την οποία θα έπρεπε συνήθως να έχετε παρατηρήσει σε οποιοδήποτε έργο Github. Επιτρέπει το στυλ και τη μορφοποίηση κειμένου πιο οικεία και ευκολότερα.
  • Δεν υπάρχει συγκεκριμένη σύνταξη / απαιτήσεις για τη δημιουργία τεκμηρίωσης. Το αίτημα και οι πληροφορίες συλλογής χρησιμοποιούνται με τον καλύτερο τρόπο για τη δημιουργία τεκμηρίωσης.
  • Μπορεί να δημοσιευτεί σε δημόσιο URL ή σε προσαρμοσμένο τομέα (για εταιρικούς χρήστες).
  • Δημιουργεί αποσπάσματα κώδικα για πραγματοποίηση κλήσεων στο API σε διαφορετικές γλώσσες όπως C #, PHP, Ruby, Python, Node κ.λπ.

Δημιουργία τεκμηρίωσης

Η γεννήτρια εγγράφων Postman αναφέρεται στη συλλογή, το φάκελο και την περιγραφή μεμονωμένων αιτημάτων και τα συγκεντρώνει κατά τη δημιουργία ή τη δημιουργία τεκμηρίωσης για τη συλλογή.

Χρησιμοποιεί διάφορες παραμέτρους αιτήματος όπως κεφαλίδες, παραμέτρους συμβολοσειράς ερωτήματος, παραμέτρους φόρμας και υποδεικνύει τη χρήση αυτών των τιμών στην τεκμηρίωση του αιτήματος.

Εδώ είναι ένα εκπαιδευτικό βίντεο:

Ας δημιουργήσουμε μια βασική συλλογή με 3 αιτήματα χρησιμοποιώντας το ίδιο δοκιμαστικό API με τα άλλα άρθρα μας. Θα προσθέσουμε κάποιες πληροφορίες στην περιγραφή της συλλογής, καθώς και στα μεμονωμένα αιτήματα και επίσης θα δημιουργήσουμε μερικά παραδείγματα αιτήσεων και απαντήσεων, τα οποία θα ληφθούν επίσης κατά τη δημιουργία της τεκμηρίωσης.

Ακολουθήστε τα παρακάτω βήματα για την προσθήκη βασικών πληροφοριών σχετικά με τα αιτήματα και, στη συνέχεια, τη δημιουργία της τεκμηρίωσης.

# 1) Δημιουργήστε μια συλλογή με 3 αιτήματα, δηλαδή Εγγραφή χρήστη, Χρήστης σύνδεσης και Λήψη χρήστη (Ανατρέξτε στην ενότητα εδώ για αιτήματα ωφέλιμων φορτίων και διευθύνσεων URL API).

#δύο) Τώρα ας προσθέσουμε μερικές πληροφορίες σε μορφή markdown στη συλλογή. Το Markdown είναι μια τυπική μορφή που χρησιμοποιείται για σχεδόν όλα τα έγγραφα στο Github (Για περισσότερες πληροφορίες σχετικά με το markdown ανατρέξτε εδώ ).

Θα προσθέσουμε μερικές πληροφορίες στην περιγραφή της συλλογής με τη μορφή υπογραφής όπως παρακάτω.

Περιγραφή συλλογής σε μορφή markdown

Για προεπισκόπηση της εμφάνισης του markdown, ανατρέξτε στην πύλη ιστού ανοιχτού κώδικα εδώ.

Τεκμηρίωση Markdown

# 3) Τώρα θα προσθέσουμε τις περιγραφές σε μεμονωμένα αιτήματα στη συλλογή. Παρόμοια με τη συλλογή, υποστηρίζεται και η μορφή υπογραφής για περιγραφές αιτημάτων (Για πιο αναλυτικές πληροφορίες σχετικά με τον οδηγό κατάργησης, ανατρέξτε στην ενότητα εδώ ).

Ας δούμε ένα δείγμα ενός από τα αιτήματα για καταχώριση τελικού σημείου χρήστη (Το ίδιο μπορεί να εφαρμοστεί και σε άλλα αιτήματα).

Κείμενο κατάργησης:

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

Προεπισκόπηση Markdown:

Προεπισκόπηση Markdown

# 4) Για όλα τα τελικά σημεία του API, ας καταγράψουμε ή αποθηκεύσουμε ένα παράδειγμα που θα χρησιμοποιούσε η γεννήτρια τεκμηρίωσης.

Ένα παράδειγμα δεν είναι παρά ένα δείγμα αίτησης-απόκρισης για το αίτημα API. Η αποθήκευση της απόκρισης ως παράδειγμα επιτρέπει στη γεννήτρια τεκμηρίωσης να την καταγράψει ως μέρος της ίδιας της τεκμηρίωσης.

Για να αποθηκεύσετε ένα παράδειγμα, πατήστε το 'Στείλετε' για να εκτελέσετε το αίτημα και στην καρτέλα απόκρισης, κάντε κλικ στο Αποθήκευση απόκρισης -> Αποθήκευση ως παράδειγμα .

Αποθήκευση παραδείγματος

Μόλις αποθηκευτεί το παράδειγμα, παραμένει στη συλλογή και μπορεί να προσπελαστεί οποιαδήποτε στιγμή στο μέλλον μέσω ενός Παραδείγματα σύνδεσμος στο εργαλείο δημιουργίας αιτημάτων.

# 5) Μόλις προστεθούν όλες οι παραπάνω πληροφορίες, ας δούμε πώς να δημιουργήσετε μια προεπισκόπηση τεκμηρίωσης.

Ανοίξτε τις επιλογές συλλογής και κάντε κλικ στο ' Δημοσίευση εγγράφων '.

Δημοσίευση εγγράφων

Σημείωση: Ένα σημαντικό πράγμα που πρέπει να σημειωθεί εδώ είναι ότι μόνο οι εγγεγραμμένοι χρήστες στο Postman θα μπορούν να χρησιμοποιούν τη δυνατότητα Δημοσίευση εγγράφων στο Postman. Η εγγραφή είναι δωρεάν, αλλά πρέπει να γίνει μέσω του λογαριασμού email σας. Υπάρχουν άλλες δυνατότητες / δυνατότητες όπως κοινή χρήση συλλογών και χώρων εργασίας, δημιουργία οθονών κ.λπ., που προστίθενται στους εγγεγραμμένους λογαριασμούς.

# 6) Μια φορά ' Δημοσίευση εγγράφων Εκτελείται, ανοίγει μια καρτέλα προγράμματος περιήγησης με τις λεπτομέρειες της συλλογής Postman (εσωτερικά η Postman φιλοξενεί αυτήν τη συλλογή στους δικούς της διακομιστές, καθώς και στο τοπικό σύστημα αρχείων του χρήστη).

Συλλογή τεκμηρίωσης

Κάντε κλικ στο 'Προεπισκόπηση' για να δείτε την τεκμηρίωση πριν από τη δημοσίευσή της.

' Δημοσίευση συλλογής Ο σύνδεσμος θα δημοσιεύσει την τεκμηρίωση σε μια δημόσια προσβάσιμη διεύθυνση URL. Γενικά δεν συνιστάται η δημοσίευση API με ευαίσθητες πληροφορίες εξουσιοδότησης για δημοσίευση στη δημόσια διεύθυνση URL. Τέτοια API μπορούν να δημοσιευτούν χρησιμοποιώντας προσαρμοσμένους τομείς με εταιρικούς λογαριασμούς του Ταχυδρόμου.

# 7) Ας δούμε πώς φαίνεται η προεπισκόπηση τεκμηρίωσης. Κάνοντας κλικ στο ' Προεπισκόπηση τεκμηρίωσης 'Ανοίγει την τεκμηρίωση σε λειτουργία προεπισκόπησης που φιλοξενείται στους διακομιστές του Postman. Ας δούμε ποιες διαφορετικές λεπτομέρειες καταγράφονται στην τεκμηρίωση (Όπως διαμορφώσαμε σε διαφορετικά μέρη. Για παράδειγμα , περιγραφή συλλογής, περιγραφή αιτήματος και παραδείγματα).

Δείγμα τεκμηρίωσης ταχυδρόμου

Αίτημα περιγραφής στο Markdown

Στα παραπάνω 2 στιγμιότυπα οθόνης, μπορείτε να δείτε ότι όλες οι πληροφορίες που προστέθηκαν στη συλλογή και τις περιγραφές αιτημάτων καταγράφονται με τρόπο υπογραφής κατά την προεπισκόπηση τεκμηρίωσης.

συστήματα σημείων πωλήσεων για το iPad

Επίσης, η τεκμηρίωση από προεπιλογή παρέχει δεσμεύσεις γλώσσας όπως επισημαίνονται και αυτό καθιστά πολύ πιο εύκολο για κάποιον που θέλει άμεσα να υποβάλει αίτημα API στην αναφερόμενη γλώσσα.

# 8) Σας επιτρέπει επίσης να εκτελέσετε πολύ βασικές τροποποιήσεις στυλ, όπως αλλαγή του χρώματος φόντου, αλλαγή του χρώματος φόντου και προσκηνίου των προτύπων κεφαλίδας, κ.λπ. σημαντικές λεπτομέρειες σχετικά με το API.

συμπέρασμα

Σε αυτό το σεμινάριο, διαβάσαμε την υποστήριξη τεκμηρίωσης API που παρέσχε η Postman, χρησιμοποιώντας την οποία μπορούμε να δημιουργήσουμε μια όμορφη εμφάνιση, στιλ τεκμηρίωσης με ελάχιστη προσπάθεια.

Επιτρέπει επίσης πολλά καλά πρότυπα και στυλ που καθορίζονται από το χρήστη που θα μπορούσαν να εφαρμοστούν στα παραγόμενα έγγραφα και επιτρέπει επίσης τη δημοσίευση τεκμηρίωσης σε μια δημόσια διεύθυνση URL.

Για ιδιωτικά τελικά σημεία API, υπάρχει επίσης μια διάταξη για τη δημοσίευση τεκμηρίωσης σε έναν προσαρμοσμένο τομέα που θα μπορούσε να διαμορφωθεί για εταιρικούς λογαριασμούς ή χρήστες.

Περαιτέρω ανάγνωση = >> Πώς να δημοσιεύσετε συμβόλαιο Pact στο Pact Broker

=> Επισκεφθείτε εδώ για να μάθετε ταχυδρόμος από το μηδέν.

Συνιστώμενη ανάγνωση

^