OpenAPI ve Sözleşme Dosyaları
apps/api/openapi.json, controller ve OpenAPI tanımlarından üretilen,
seçilmiş geliştirici yollarını içeren OpenAPI 3.0 belgesidir. API davranışı
controller, DTO, guard ve yanıt dönüştürücüsüyle belirlenir; üretilmiş şemanın
varlığı tek başına tüm çalışma davranışının eksiksiz modellendiğini kanıtlamaz.
Sözleşme Kaynakları ve Erişim
| Kaynak | Kullanım |
|---|---|
| OpenAPI JSON dosyasını indir | Geliştirici sitesinin statik sözleşme dosyası; API kopyasıyla byte-eşitliği güncellik kapısında denetlenir |
apps/api/openapi.json | Repo içinde üretilmiş, sürüm kontrolündeki sözleşme |
https://api.mevzuatradar.com/api/docs-json | Etkinleştirildiğinde canlı OpenAPI JSON belgesi |
https://api.mevzuatradar.com/api/docs | Etkinleştirildiğinde etkileşimli API arayüzü |
| API referansı sayfaları | Parametre, yanıt ve davranış açıklamaları |
Üretimde OpenAPI varsayılan olarak kapalıdır. API_DOCS_ENABLED=true ile
açıldığında API_DOCS_BASIC_AUTH_USERNAME ve API_DOCS_BASIC_AUTH_PASSWORD
zorunludur; eksikse uygulama yapılandırma hatası verir. Her iki yol Basic
kimlik doğrulamasıyla korunur. Yetkisiz erişimde HTTP 401,
WWW-Authenticate: Basic realm="MevzuatRadar API Docs" ve düz metin
Authentication required yanıtı döner. Bu erişim modeli x-api-key veya
Bearer JWT değildir. Üretim dışı ortamda varsayılan olarak açıktır ve bu
Basic koruması uygulanmaz.
24 Ekim 2026 19:23 UTC kimliksiz GET gözleminde canlı /api/docs-json ve
/api/docs yolları HTTP 404 döndürmüştür. Bu tarihli gözlem, kimliksiz
indirilebilir bir canlı sözleşme bulunduğu iddiasına dayanak oluşturmaz;
sonraki dağıtımlarda erişim durumu ayrıca kontrol edilir.
Herkese Açık Yol İzin Listesi
Buradaki “herkese açık”, geliştirici belgesine dahil edilme kapsamıdır; kimliksiz erişim anlamına gelmez.
| Yol | Yöntem | Kimlik doğrulama |
|---|---|---|
/api/v1/public/source-stats | GET | Yok |
/api/v1/public/regulations | GET | Yok |
/api/v1/changes | GET | x-api-key veya desteklenen Bearer JWT |
/api/v1/catalog/search | GET | search:read anahtarı veya yetkili JWT |
/api/v1/catalog/regulations/{id} | GET | regulations:read anahtarı veya yetkili JWT |
/api/v1/catalog/sector-taxonomy/active | GET | regulations:read anahtarı veya yetkili JWT |
/api/v1/catalog/sector-taxonomy/nodes | GET | regulations:read anahtarı veya yetkili JWT |
/api/v1/events | GET | regulations:read anahtarı veya yetkili JWT |
/api/v1/deadlines | GET | x-api-key veya desteklenen Bearer JWT |
/api/v1/actions | GET | x-api-key veya desteklenen Bearer JWT |
/api/v1/verification-reports | GET | x-api-key veya desteklenen Bearer JWT |
/api/v1/verification-reports/{id} | GET | x-api-key veya desteklenen Bearer JWT |
/api/v1/board-reports | GET | x-api-key veya desteklenen Bearer JWT |
/api/v1/board-reports/{id} | GET | x-api-key veya desteklenen Bearer JWT |
/api/v1/evidence-packs/{id} | GET | x-api-key veya desteklenen Bearer JWT |
/api/v1/webhooks | GET, POST | webhooks:manage Enterprise anahtarı veya ADMIN/settings JWT |
/api/v1/webhooks/{id} | GET, PUT, DELETE | webhooks:manage Enterprise anahtarı veya ADMIN/settings JWT |
/api/v1/webhooks/{id}/test | POST | webhooks:manage Enterprise anahtarı veya ADMIN/settings JWT |
/api/v1/webhooks/{id}/rotate-secret | POST | webhooks:manage Enterprise anahtarı veya ADMIN/settings JWT |
/api/v1/webhooks/{id}/deliveries | GET | webhooks:manage Enterprise anahtarı veya ADMIN/settings JWT |
API anahtarı izinleri ve JWT yetkileri ilgili endpointte ayrıca uygulanır.
Webhook yönetiminde işlem türüne göre settings:read veya settings:write
izni gerekir. İzin listesi dışındaki bir yolun belgede bulunmaması,
uygulamada bulunmadığı anlamına gelmez. Sağlık ve oturum kaynak kataloğu bu
belgenin kapsamı dışındadır.
Güncellik Komutları
Repo kökünden kullanılan komutlar:
npm run openapi:generate -w @mevzuat-radar/api
cp apps/api/openapi.json apps/docs/public/openapi.json
npm run openapi:check -w @mevzuat-radar/apiopenapi:generate, apps/api/openapi.json dosyasını yeniden yazar.
openapi:check, üretimi --check ile çağırır; dosya eksikse veya yeniden
üretilen metin farklıysa başarısız olur. Kontrol ayrıca üretimin çalışma
bağımlılıklarına eriştiğini gösteren bağlantı hata sinyallerini reddeder.
Bu karşılaştırma, belgelenmiş şemayla gerçek yanıt arasında anlamsal
uygunluk testi yerine geçmez.
SDK Kullanımı
OpenAPI dosyası istemci geliştirme için kullanılabilir. Node.js ve Python SDK kapsamı, kurulum ve paket erişimi ilgili SDK sayfalarından ayrıca kontrol edilir. Yukarıdaki komutlar SDK üretmez veya paket yayımlamaz. Entegrasyon denemeleri Entegrasyon Testi sayfasında anlatılır.
Katalog, Olay API’leri ve SDK Eşitliği
Güncellik kontrolü yeniden üretilen API şemasını, indirilebilir byte-eşit kopyayı ve Node/Python kaynak istemcilerinin yol envanterini denetler. SDK’daki her yol OpenAPI içinde, katalog ve olay uçları’nin katalog, olay, değişiklik ve Webhook yolları da iki istemcide bulunmalıdır. Eski bir kopya veya eksik SDK yolu kontrolü başarısız kılar. SDK kaynaklarının bulunması npm/PyPI yayını anlamına gelmez.