İstemci ve tip üretimi

Public API’nin tam sözleşmesi OpenAPI 3.1 olarak yayınlanır:

• Canlı: https://api.mirac-ozdemir.com/openapi.json (diğer adı /openapi-public.json). Yanıt önbelleklenebilir (max-age=300) ve CORS’a açıktır.
• Bu sitede: API Referansı, aynı sözleşmeden üretilir.

Sözleşme yalnızca bu dokümandaki 7 public işlemi içerir. Türkçe açıklamalar, örnekler ve araç tanımı biçiminin ayrıntılı JSON Schema’sı dahildir.

TypeScript tipleri

openapi-typescript ile tipleri tek komutla üretin:

npx openapi-typescript https://api.mirac-ozdemir.com/openapi.json -o src/api/schema.d.ts

Üretilen tipleri, tip güvenli bir fetch sarmalayıcısıyla (openapi-fetch) kullanın:

import createClient from 'openapi-fetch';
import type { paths } from './api/schema';

const client = createClient<paths>({ baseUrl: 'https://api.mirac-ozdemir.com' });

const { data, error } = await client.POST('/v1/public/tools/by-key/{key}/calculate', {
  params: { path: { key: 'kdv' } },
  body: { inputs: { amount: '1000', mode: 'exclusive', vatRateOption: 'standard' } },
});
if (error) throw new Error(error.error.code);
console.log(data.data.result);

İpucu

Şema çıktısını repoya ekleyip CI’da yenileyin; sözleşme değiştiğinde derleme zamanında fark edersiniz. Geriye dönük uyumlu eklemeler tipleri bozmaz.

Diğer diller için istemci üretimi

Sözleşme standart OpenAPI olduğu için OpenAPI Generator veya benzeri araçlar çalışır:

Python

npx @openapitools/openapi-generator-cli generate -i https://api.mirac-ozdemir.com/openapi.json -g python -o ./mo-client

C#

npx @openapitools/openapi-generator-cli generate -i https://api.mirac-ozdemir.com/openapi.json -g csharp -o ./MoClient

PHP

npx @openapitools/openapi-generator-cli generate -i https://api.mirac-ozdemir.com/openapi.json -g php -o ./mo-client

Java

npx @openapitools/openapi-generator-cli generate -i https://api.mirac-ozdemir.com/openapi.json -g java -o ./mo-client

Üretilen istemcilerde ondalık alanlar string tipindedir; bunları dilinizin ondalık türüne (Decimal, decimal, BigDecimal) kendiniz çevirin.

API istemcilerine aktarma

OpenAPI adresini doğrudan içe aktarabilirsiniz:

• Postman: Import → Link → https://api.mirac-ozdemir.com/openapi.json.
• Insomnia: Create → Import → From URL.
• Bruno: Import collection → OpenAPI.
• Swagger UI / Redoc: adresi doğrudan verin; CORS açıktır.

Her operasyonun örnek istek ve yanıtları sözleşmede hazırdır. Tarayıcıda denemek için Oyun alanını da kullanabilirsiniz.