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

Γιατί οι περισσότερες τεκμηριώσεις API αποτυγχάνουν

Περιγράφουν τα τελικά σημεία και παραλείπουν τα μέρη που πραγματικά σταματούν τους ανθρώπους: πώς να κάνουν έλεγχο ταυτότητας, πώς μοιάζει μια ρεαλιστική αίτηση, τι σημαίνει το σφάλμα και τι να κάνουν γι' αυτό. Ο αναγνώστης στη συνέχεια ανοίγει ένα αίτημα υποστήριξης, το οποίο είναι το κόστος που η τεκμηρίωση υπάρχει για να αφαιρέσει.

Πώς το γράφω

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

Τι περιέχει η τεκμηρίωση

• Έλεγχος ταυτότητας: απόκτηση διακριτικού, ανανέωσή του και τι συμβαίνει όταν λήγει εν μέσω συνεδρίας.
• Κάθε τελικό σημείο με παραμέτρους, ένα πλήρες παράδειγμα αιτήματος και το πραγματικό σχήμα απόκρισης.
• Μια αναφορά σφαλμάτων που αντιστοιχίζει κάθε κωδικό σφάλματος σε μια αιτία και μια διόρθωση, αντί να επαναλαμβάνει απλώς το μήνυμα.
• Μια διαδρομή έναρξης που οδηγεί έναν νέο προγραμματιστή από το μηδέν σε μια επιτυχημένη κλήση σε λιγότερο από δέκα λεπτά.
• Όρια ρυθμού, σελιδοποίηση, webhooks και ιδιοδυναμία εξηγούνται όπου πραγματικά εφαρμόζονται.

Μορφή

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

Τι χρειάζομαι

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

Δεν περιλαμβάνεται

Κείμενο μάρκετινγκ. Αυτό τεκμηριώνει τι κάνει το λογισμικό, με ακρίβεια· η σελίδα προορισμού είναι μια διαφορετική τέχνη.

Χρόνος παράδοσης και επικοινωνία

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