Τεκμηρίωση API: OpenAPI, Swagger, Postman

TL, DR

OpenAPI - πηγή αλήθειας: σύμβαση → SDK → moki → tests → portal.
Swagger UI/Redoc - αναγνώσιμη βιτρίνα· Ταχυδρόμος - εκτελέσιμα σενάρια.
Ράβουμε σε χιτώνια, ελέγχουμε, παραδείγματα και συστήματα σφαλμάτων, δημιουργούμε διακομιστές SDK και Mock, δημοσιεύουμε μια πύλη dev και «Sunset».

1) Στόχοι και αρχές

Σύμβαση 1 (OpenAPI). Όλα τα άλλα δημιουργούνται.
Η τεκμηρίωση είναι εκτελέσιμη: οι αιτήσεις δειγματοληψίας υποβάλλονται σε δοκιμή σε Postman/CLI.
Προκαθορισμένη ασφάλεια: συστήματα σφάλματος, όρια, επαλήθευση ταυτότητας.
Έκδοση και κύκλος ζωής: 'v1 '/' v2', Deprecation/Sunset, changelog.

2) Δομή OpenAPI (ελάχιστος σκελετός)

yaml openapi: 3. 0. 3 info:
title: Payments API version: 1. 2. 0 description: >
Payment transactions: auth/capture/refund/payout. All responses contain trace_id.
servers:
- url: https://api. example. com/v1 tags:
- name: Payments
- name: Payouts components:
securitySchemes:
oauth2:
type: oauth2 flows:
clientCredentials:
tokenUrl: https://idp. example. com/oauth/token scopes:
payments: read: read payments: write: write payments schemas:
Error:
type: object required: [error, error_description, trace_id]
properties:
error: { type: string }
error_description: { type: string }
trace_id: { type: string, format: uuid }
security:
- oauth2: [payments:read]
paths:
/payments/{id}:
get:
summary: Receive payment tags: [Payments]
parameters:
- in: path name: id required: true schema: { type: string, format: uuid }
responses:
'200':
description: Content succeeded:
application/json:
schema: { $ref: '#/components/schemas/Payment' }
'404': { $ref: '#/components/responses/NotFound' }
components:
responses:
NotFound:
description: Content not found:
application/json:
schema: { $ref: '#/components/schemas/Error' }

• Αποσύνθεση σχημάτων/αποκρίσεων/παραμέτρων/αντισταθμιστικών φορέων σε «συμβατικούς».
• Περιγράψτε securitSchemes (OAuth2/JWT/HMAC) και εφαρμόστε σε «διαδρομές »/« παγκόσμιο» επίπεδο.

3) Πρότυπο σφάλματος και μεταδεδομένα

yaml components:
schemas:
ApiError:
type: object required: [error, error_description, trace_id]
properties:
error: { enum: [invalid_request, not_found, rate_limited, internal] }
error_description: { type: string }
trace_id: { type: string, format: uuid }

Πάντα το έγγραφο 429 (όριο ταχύτητας), 401/403, και οι επικεφαλίδες 'X- Limit-', 'Retry-After'.

4) Παραδείγματα: αίτημα/απάντηση, μπούκλα και SDK

Για κάθε τελικό σημείο: ελάχιστο και εκτεταμένο παράδειγμα.
Δημιουργία curl και κωδικών snippets (JS/Python/Go) από το OpenAPI; Μην γράφετε με τα χέρια σας.
Εφαρμογή πραγματικών τιμών: UUID, ημερομηνία ISO, ποσά σε «ήσσονος σημασίας» (λεπτά).

yaml examples:
ok:
value:
id: "pay_123"
amount_minor: 1099 currency: "EUR"
status: "captured"
created_at: "2025-11-03T12:34:56Z"

5) Swagger UI/Redoc - πώς να αναρτήσετε

1. Swagger UI (διαδραστική, try-it-out),

2. Redoc (αναγνώσιμες μακριές σελίδες).

Συμπεριλαμβάνονται: σκοτεινό θέμα, αναζήτηση, επιλογέας έκδοσης ('v1', 'v2'), πανό αποσύνθεσης.

Απόκρυψη «Δοκιμάστε το» για τον τομέα παραγωγής, αφήστε το στο κουτί άμμου.

6) Συλλογές ταχυδρόμων: Ζωντανά σενάρια

Αυτόματη παραγωγή της συλλογής από το OpenAPI και υποστηρικτικές περιβαλλοντικές μεταβλητές ('{{baseUrl}}}', '{{accessToken}}').
Προσθήκη προγνώσεων (απόκτηση μιας μάρκας) και μετά τις δοκιμές (επιβεβαίωση κατάστασης/σχημάτων).
Διάρρηξη φακέλων: Auth, Payments, Payouts, Webhooks.
Οθόνες εξαγωγής (προγραμματισμένες) για κρίσιμες διαδρομές.

js pm. test("status is 200", () => pm. response. code === 200);
pm. test("schema valid", () => tv4. validate(pm. response. json(), pm. collectionVariables. get("schema_payment")));

7) Μόκι και το αμμώδες κουτί

Δημιουργία ενός διακομιστή mock από το OpenAPI (παραδείγματα/' παράδειγμα '/' παραδείγματα ').
Αναφέρατε τους περιορισμούς των mocs: ταυτότητα, καθυστερήσεις, τυχαία σφάλματα (για UAT).
Sandbox εγγράφου έναντι διαφορών (όρια, δεδομένα, καθυστερήσεις).

8) Αυτοπαραγωγή SDK

Από το OpenAPI, δημιουργήστε επίσημα SDK (TypeScript, Python, Go).
Πολιτική απελευθέρωσης SDK = SemVer, χαρτογράφηση έκδοσης API.
Στο README SDK: επαλήθευση ταυτότητας, επανασυσκευασία, ταυτότητα, επεξεργασία 429/Retry-After.

9) Σύνδεση, έλεγχος θραύσης και CI

Γραμμές: φασματικά (στυλ/αντι-μοτίβα), openapi-diff (έλεγχοι θραύσης).

• επικυρωτής κυκλώματος,
• χιτώνιο,
• δοκιμές σύμβασης έναντι του εξυπηρετητή ioc,
• συγκρότημα Swagger/Redoc/συλλογής,
• δημοσίευση στην πύλη (staging→prod),
• Απερήμωση/συναγερμός ηλιοβασιλέματος.

10) Εκδοχή, απερήμωση, ηλιοβασίλεμα

Έκδοση σε URI ('/v1 ') και σε' info. έκδοση ".
Σημαίες αποσύνθεσης: 'Deprecation: true', 'Sunset: <RFC1123 date>', 'Link: <changelog>' headers.
Στην πύλη - ένα πανό και ένα χρονοδιακόπτη πριν την αποσύνδεση. Οι συλλογές ταχυδρόμων για το v1 είναι κατεψυγμένες (διορθώσεις σφαλμάτων μόνο).

11) Ασφάλεια και προστασία της ιδιωτικής ζωής στο λιμένα

Μην δημοσιεύετε μυστικά, εσωτερικά URL, πραγματικά PAN/PII.
Για ευαίσθητα πεδία - απόκρυψη και απομονωμένα παραδείγματα.
Το swagger «Δοκιμάστε το» → μόνο σε αμμοκιβώτιο, με όρια ταχύτητας.
Περιγράψτε σαφώς OAuth2/OIDC, HMAC (για webhooks) και mTLS (εάν απαιτείται).

12) Συμβάσεις οδηγού στυλ

Πληθυντικός πόρων: «/πληρωμές », «/πληρωμές».
Αναγνωριστικά: «pay _',» po _', UUIDv4 ή ksuid.
Ημερομηνίες - UTC ISO-8601, χρήματα - «ποσό _ ήσσονος σημασίας + νόμισμα».
Pagination - με βάση το δρομέα ('? δρομέας = & όριο = '), σταθερή διαλογή.
Idempotency - 'Idempotency-Key' για μεταλλάξεις.
Σταθερό αντικείμενο 'meta' και 'links' για λίστες.

13) Το τμήμα «Webhooks» της δεξαμενής

Χωριστή ενότητα με φάκελο γεγονότων, υπογραφές HMAC, χρονοθυρίδα, retrays, κωδικούς απόκρισης.
Φορείς δειγματοληψίας και συλλογή ταχυδρόμων για επαλήθευση τοπικής υπογραφής.
αναπαραγωγή/τελικά σημεία DLQ και λίστα ελέγχου UAT.

14) Πύλη Dev: Ρόλοι και δημοσίευση

Τμήματα: Επισκόπηση, εκκίνηση, ταυτοποίηση, τελικά σημεία, παραδείγματα, Webhooks, SDK, περιορισμοί, Changelog.
Ρόλοι: Steward API (πρότυπα), Domain Owner (περιεχόμενο), Tech Writer (επεξεργασία), DevRel (πύλη/κοινότητα).
Χαρακτηριστικό: αναζήτηση μέσω πεδίων σχήματος, αντιγραφή δειγμάτων, «συλλογή αιτήματος» → ταχυδρόμος.

15) Κατάλογοι ελέγχου

• Το OpenAPI είναι έγκυρο. χιτώνιο χωρίς σφάλματα.

• Παραδείγματα καλύπτουν 200/4xx/429/5xx.
• Ασφάλεια: Περιγραφόμενα αυτοσχέδια σχέδια, χωρίς μυστικά.
• Σχηματίστηκε Swagger/Redoc και Postman (prod/sandbox).
• Η SDK δημιούργησε και δημοσίευσε.
• Ενημερωμένο changelog και επιλογέας έκδοσης.

• Συμπεριλαμβάνονται κεφαλίδες αποσύνθεσης/ηλιοβασιλέματος.
• Banner στην πύλη, επιστολές προς τους εταίρους.
• Οι κληροδοτημένες μετρήσεις κλήσεων πέφτουν στο στόχο.

16) Αντι-μοτίβα

Διπλές πηγές αλήθειας (wiki ≠ OpenAPI).
Παραδείγματα του «με το μάτι» χωρίς να τρέχει στο Postman.
Έλλειψη ενιαίου μορφότυπου σφάλματος.
Έκδοση «in query parameter» αντί URI/domain.
Στριφογύρισμα με πρόσβαση στα τρόφιμα και χωρίς όρια.
Ασυνεπή συστήματα επισήμανσης και εξακρίβωσης της ταυτότητας.

17) Mini snippets της αυτοματοποίησης

bash openapi2postmanv2 -s openapi. yaml -o postman. json -p

yaml steps:
- run: spectral lint openapi. yaml
- run: openapi-diff --fail-on-breaking main. yaml openapi. yaml
- run: redoc-cli bundle openapi. yaml -o site/redoc. html
- run: swagger-cli bundle openapi. yaml -o site/swagger. json
- run: openapi2postmanv2 -s openapi. yaml -o site/postman. json -p
- run: npm run deploy:portal

18) Εντοπισμός και διαθεσιμότητα

Ατομικό 'info. ή δύο συνελεύσεις πύλης (EN/RU).
Γλωσσάριο (KYC/AML, πληρωμή, ταυτότητα).
Αντίθεση, πλοήγηση πληκτρολογίου, σκοτεινό θέμα.

Περίληψη

Συγκεντρώστε έναν αγωγό τεκμηρίωσης: ένα ενιαίο συμβόλαιο OpenAPI → γραμμές και ελέγχους θραύσης → Swagger/Redoc showcases → Postman συλλογές και ένα mock server → SDK → μια πύλη έκδοσης και Sunset. Τακτικά παραδείγματα, μια ενιαία μορφή σφάλματος και μια ισχυρή επαλήθευση ταυτότητας θα μετατρέψουν την τεκμηρίωση από PDF στο ράφι σε εργαλείο ολοκλήρωσης εργασίας, επιταχύνοντας τους συνεργάτες και μειώνοντας το κόστος υποστήριξης.