API belgeleri: OpenAPI, Swagger, Postman

TL; DR

OpenAPI - gerçeğin kaynağı: contract - SDK - moki - tests - portal.
Swagger UI/Redoc - okunabilir vitrin; Postacı - çalıştırılabilir komut dosyaları.
Linters, breaking-checks, örnekler ve hata şemaları dikiyoruz, SDK'lar ve Mock sunucuları üretiyoruz, sürümlü bir dev portalı ve "Sunset" yayınlıyoruz.

1) Hedefler ve ilkeler

Birinci sözleşme (OpenAPI). Diğer her şey üretilir.
Dokümantasyon çalıştırılabilir: örnek istekleri Postman/CLI'da test edilir.
Varsayılan güvenlik: hata şemaları, sınırlar, kimlik doğrulama.
Sürüm oluşturma ve yaşam döngüsü: 'v1'/' v2', Amortisman/Günbatımı, changelog.

2) OpenAPI yapısı (minimum iskelet)

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' }

• Şemaları/yanıtları/parametreleri/requestBodies öğelerini 'bileşenlere' ayrıştırın.
• SecuritySchemes (OAuth2/JWT/HMAC) tanımlayın ve 'paths'/' global' düzeyinde uygulayın.

3) Hata standardı ve meta veriler

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 }

Her zaman 429 (hız sınırı), 401/403 ve 'X-RateLimit-', 'Retry-After' başlıklarını belgeleyin.

4) Örnekler: istek/yanıt, kıvrılma ve SDK

Her uç nokta için: minimum ve genişletilmiş örnek.
OpenAPI'den kıvrılma ve kod parçacıkları (JS/Python/Go) oluşturun; Ellerinizle yazmayın.
Gerçek değerleri uygulayın: UUID, ISO tarihi, "minör" (sent) cinsinden toplamlar.

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 - nasıl gönderilir

1. Swagger UI (etkileşimli, deneyin-dışarı),

2. Redoc (okunabilir uzun sayfalar).

Include: dark theme, search, version selector ('v1', 'v2'), Deprecation banner.

Üretim etki alanı için "Deneyin'i gizleyin, sanal alanda izin verin.

6) Postacı koleksiyonları: Canlı senaryolar

Koleksiyonu OpenAPI ve destek ortamı değişkenlerinden ('{{baseUrl}}', '{{accessToken}}') otomatik olarak oluşturun.
Ön testler (bir belirteç elde etme) ve testler sonrası (durumu/şemaları belirtin) ekleyin.
Klasörlere ayrılın: Auth, Payments, Payouts, Webhooks.
Kritik rotalar için monitörleri (zamanlanmış) dışa aktarın.

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) Moki ve kum havuzu

OpenAPI'den sahte bir sunucu oluşturun (örnekler/' örnekler'/' örnekler ').
Mocs sınırlamalarını belirtin: idempotency, gecikmeler, rastgele hatalar (UAT için).
Belge sanal alanı vs ürün farklılıkları (limitler, veriler, gecikmeler).

8) SDK otomatik oluşturma

OpenAPI'den resmi SDK'lar (TypeScript, Python, Go) oluşturun.
SDK sürüm politikası = SemVer, API sürüm eşlemesi.
README SDK'sında: kimlik doğrulama, yeniden ödeme, idempotency, 429/Retry-After işleme.

9) Linting, kırılma kontrolü ve CI

Çizgileri: spektral (stiller/anti-desenler), openapi-diff (breaking-checks).

• Devre doğrulayıcı,
• Linter,
• IOC sunucusuna karşı sözleşme testleri,
• Swagger/Redoc/collection assembly,
• Portala yayın (evreleme - prod),
• Kullanımdan kaldırma/Gün batımı uyarısı.

10) Sürüm, Amortisman, Gün batımı

URI'de ('/v1 ') ve' bilgi'de sürüm. Versiyon '.
Kullanımdan kaldırma bayrakları: 'Amortisman: doğru', 'Gün batımı: <RFC1123 tarihi>', 'Bağlantı: <changelog>' başlıkları.
Portalda - bağlantı kesilmeden önce bir afiş ve zamanlayıcı; V1 için postacı koleksiyonları dondurulmuştur (yalnızca hata düzeltmeleri).

11) Rıhtımda güvenlik ve gizlilik

Sırları, dahili URL'leri, gerçek PAN/PII'yi yayınlamayın.
Hassas alanlar için - maskeleme ve saplama örnekleri.
Swagger "Deneyin" - sadece sandbox'a, oran sınırlarıyla.
OAuth2/OIDC, HMAC (webhook'lar için) ve mTLS'yi (gerekirse) açıkça tanımlayın.

12) Stil Kılavuzu sözleşmeleri

Kaynaklar çoğul:'/payments ','/payments'.
Tanımlayıcılar: 'pay _'', po _', UUIDv4 veya kusuid.
Tarihler - UTC ISO-8601; money - 'amount _ minor + currency'.
Sayfalama - imleç tabanlı ('? İmleç = & limit = '), kararlı sıralama.
Idempotency - Mutasyonlar için 'Idempotency-Key'.
Listeler için kararlı nesne 'meta've' bağlantılar '.

13) Rıhtımın "Webhooks" bölümü

Olay zarfı, HMAC imzaları, zaman penceresi, retrays, yanıt kodları ile ayrı bölüm.
Yerel imza doğrulaması için örnek olay organları ve Postman koleksiyonu.
Yeniden oynatma/DLQ uç noktaları ve UAT kontrol listesi.

14) Dev Portal: Roller ve Yayın

Bölümler: Genel Bakış, Başlarken, Kimlik Doğrulama, Uç Noktalar, Örnekler, Webhooks, SDK, Kısıtlamalar, Changelog.
Roller: Steward API (standartlar), Domain Owner (içerik), Tech Writer (düzenleme), DevRel (portal/topluluk).
Özellik: şema alanları arasında arama, kopya örnekleri, "talep toplamak" - Postacı.

15) Kontrol listeleri

• OpenAPI geçerlidir; hatasız linter.
• Örnekler 200/4xx/429/5xx kapsar.
• Güvenlik: Açıklanan auth şemaları, sır yok.
• Swagger/Redoc ve Postman (prod/sandbox) oluşturuldu.
• SDK oluşturuldu ve yayınlandı.
• Güncellenmiş changelog ve sürüm seçici.

• Kullanımdan kaldırma/Günbatımı başlıkları dahil.
• Portalda afiş, ortaklara mektuplar.
• Eski çağrı metrikleri hedefe düşer.

16) Anti-desenler

Gerçeğin yinelenen kaynakları (wiki ≠ OpenAPI).
Postacı'da koşmadan "gözle" örnekler.
Tek bir hata biçimi eksikliği.
URI/domain yerine "query parametresinde" sürümü.
Yiyeceğe erişimi olan ve sınırı olmayan havalı biri.
Tutarsız sayfalama ve kimlik doğrulama şemaları.

17) Otomasyonun mini parçacıkları

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) Yerelleştirme ve kullanılabilirlik

Individual 'info. description_<lang>' veya iki portal düzeneği (EN/RU).
Sözlük terimleri (KYC/AML, ödeme, idempotency).
Kontrast, klavye navigasyonu, karanlık tema.

Özet

Bir dizi dokümantasyon oluşturun: tek bir OpenAPI kontratı, linterler ve breaking-checks, Swagger/Redoc vitrinleri, Postman koleksiyonları ve sahte bir sunucu, SDK, bir sürüm portalı ve Sunset. Düzenli örnekler, tek bir hata biçimi ve güçlü kimlik doğrulama, belgeleri raftaki PDF'den çalışan bir entegrasyon aracına dönüştürerek iş ortaklarını hızlandırır ve destek maliyetlerini düşürür.