Sürümleme ve Belgeler

/v1/doc — makine-okur OpenAPI şeması

GET /v1/doc ucu, OpenAPIHono tarafından çalışma zamanında üretilen OpenAPI 3.1 JSON belgesini döner:

{
  "openapi": "3.1.0",
  "info": {
    "title": "Kaza Rehberi API",
    "version": "v1",
    "description": "Sözleşme kaynağı: backend/api-mimarisi/ — zod şemaları çalışma zamanında da doğrular."
  }
}

Bu belge, kod tabanı yeniden derlenmeden doğrudan zod şemalarından türetilir — yeni bir uç eklendiğinde ya da bir alan değiştiğinde /v1/doc otomatik güncellenir; ayrıca senkronize tutulması gereken elle yazılmış bir OpenAPI dosyası YOKTUR.

/v1/docs — Swagger UI

GET /v1/docs, /v1/doc’taki şemayı okuyup tarayıcıda gezilebilir bir Swagger UI arayüzü sunar (@hono/swagger-ui). Prod’da:

https://api.kazarehberi.com.tr/v1/docs

Kodun-doğruluğu ilkesi

@hono/zod-openapi deseninde her route, girdi/çıktı şemasını z.object({...}).openapi(...) ile tanımlar. Bu tek tanım şu üç işi birden yapar:

Gelen isteği çalışma zamanında doğrular (geçersizse 400 GIRDI_GECERSIZ).
Giden yanıtın tipini belgeler.
/v1/doc şemasına otomatik girer.

Bu nedenle doküman kodla asla sapmaz — elle senkronize edilen ayrı bir spesifikasyon dosyası yoktur.

parametre_versiyonu alanı

Hesaplama uçlarının (/v1/hesaplamalar/*) yanıt gövdelerinde bulunan parametre_versiyonu (bazı uçlarda parametreVersiyonu) alanı, hesaplamanın hangi katsayı/parametre sürümüyle üretildiğini işaretler:

{
  "hesaplamaId": "1f9c2b0e-...",
  "toplam": 12500.5,
  "kalemler": [{ "ad": "kazanç kaybı", "tutar": 12500.5 }],
  "parametre_versiyonu": 7
}

Hesaplama parametreleri (değer kaybı R/K/parça tabloları, maluliyet uzuv kataloğu, meslek çarpanları, manevi kademeler, bakım oranları, asgari ücret dönemleri vb.) admin panelinden (parametre:yonet izni) zaman içinde güncellenebilir. Bir hesaplama kaydı geçmişte hangi katsayılarla üretildiyse, parametre_versiyonu bunu sabitler — böylece:

Geçmiş bir hesaplamanın sonucu, parametreler sonradan değişse bile yeniden hesaplandığında aynı çıkar (denetlenebilirlik).
İstemciler, kullanıcıya “bu hesaplama X sürümündeki parametrelerle yapıldı” bilgisini gösterebilir.