Ana içeriğe geç
Mevzuat RadarDokümantasyon
Uygulamaya git ↗

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

KaynakKullanım
OpenAPI JSON dosyasını indirGeliştirici sitesinin statik sözleşme dosyası; API kopyasıyla byte-eşitliği güncellik kapısında denetlenir
apps/api/openapi.jsonRepo içinde üretilmiş, sürüm kontrolündeki sözleşme
https://api.mevzuatradar.com/api/docs-jsonEtkinleştirildiğinde canlı OpenAPI JSON belgesi
https://api.mevzuatradar.com/api/docsEtkinleş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.

YolYöntemKimlik doğrulama
/api/v1/public/source-statsGETYok
/api/v1/public/regulationsGETYok
/api/v1/changesGETx-api-key veya desteklenen Bearer JWT
/api/v1/catalog/searchGETsearch:read anahtarı veya yetkili JWT
/api/v1/catalog/regulations/{id}GETregulations:read anahtarı veya yetkili JWT
/api/v1/catalog/sector-taxonomy/activeGETregulations:read anahtarı veya yetkili JWT
/api/v1/catalog/sector-taxonomy/nodesGETregulations:read anahtarı veya yetkili JWT
/api/v1/eventsGETregulations:read anahtarı veya yetkili JWT
/api/v1/deadlinesGETx-api-key veya desteklenen Bearer JWT
/api/v1/actionsGETx-api-key veya desteklenen Bearer JWT
/api/v1/verification-reportsGETx-api-key veya desteklenen Bearer JWT
/api/v1/verification-reports/{id}GETx-api-key veya desteklenen Bearer JWT
/api/v1/board-reportsGETx-api-key veya desteklenen Bearer JWT
/api/v1/board-reports/{id}GETx-api-key veya desteklenen Bearer JWT
/api/v1/evidence-packs/{id}GETx-api-key veya desteklenen Bearer JWT
/api/v1/webhooksGET, POSTwebhooks:manage Enterprise anahtarı veya ADMIN/settings JWT
/api/v1/webhooks/{id}GET, PUT, DELETEwebhooks:manage Enterprise anahtarı veya ADMIN/settings JWT
/api/v1/webhooks/{id}/testPOSTwebhooks:manage Enterprise anahtarı veya ADMIN/settings JWT
/api/v1/webhooks/{id}/rotate-secretPOSTwebhooks:manage Enterprise anahtarı veya ADMIN/settings JWT
/api/v1/webhooks/{id}/deliveriesGETwebhooks: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/api

openapi: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.