happyz
/
fastapi
mirror of https://github.com/tiangolo/fastapi.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
fastapi/docs/tr/docs/advanced/generate-clients.md

11 KiB
Raw Blame History

SDK Üretme

FastAPI, OpenAPI spesifikasyonunu temel aldığı için API'leri birçok aracın anlayabildiği standart bir formatta tanımlanabilir.

Bu sayede güncel dokümantasyon, birden fazla dilde istemci kütüphaneleri (SDKs) ve kodunuzla senkron kalan test veya otomasyon iş akışları üretmek kolaylaşır.

Bu rehberde, FastAPI backend'iniz için bir TypeScript SDK üretmeyi öğreneceksiniz.

Açık Kaynak SDK Üreteçleri

Esnek bir seçenek olan OpenAPI Generator, birçok programlama dilini destekler ve OpenAPI spesifikasyonunuzdan SDK üretebilir.

TypeScript client'lar için Hey API, TypeScript ekosistemi için özel olarak tasarlanmış, optimize bir deneyim sunan bir çözümdür.

Daha fazla SDK üretecini OpenAPI.Tools üzerinde keşfedebilirsiniz.

/// tip | İpucu

FastAPI otomatik olarak OpenAPI 3.1 spesifikasyonları üretir; bu yüzden kullanacağınız aracın bu sürümü desteklemesi gerekir.

///

FastAPI Sponsorlarından SDK Üreteçleri

Bu bölüm, FastAPI'yi sponsorlayan şirketlerin sunduğu yatırım destekli ve şirket destekli çözümleri öne çıkarır. Bu ürünler, yüksek kaliteli üretilen SDK'ların üzerine ek özellikler ve entegrasyonlar sağlar.

✨ FastAPI'ye sponsor olarak{.internal-link target=_blank} ✨ bu şirketler, framework'ün ve ekosisteminin sağlıklı ve sürdürülebilir kalmasına yardımcı olur.

Sponsor olmaları aynı zamanda FastAPI topluluğuna (size) güçlü bir bağlılığı da gösterir; yalnızca iyi bir hizmet sunmayı değil, aynı zamanda güçlü ve gelişen bir framework olan FastAPI'yi desteklemeyi de önemsediklerini gösterir. 🙇

Örneğin şunları deneyebilirsiniz:

Bu çözümlerin bazıları açık kaynak olabilir veya ücretsiz katman sunabilir; yani finansal bir taahhüt olmadan deneyebilirsiniz. Başka ticari SDK üreteçleri de vardır ve internette bulunabilir. 🤓

TypeScript SDK Oluşturma

Basit bir FastAPI uygulamasıyla başlayalım:

{* ../../docs_src/generate_clients/tutorial001_py39.py hl[7:9,12:13,16:17,21] *}

Path operation'ların, request payload ve response payload için kullandıkları modelleri Item ve ResponseMessage modelleriyle tanımladıklarına dikkat edin.

API Dokümanları

/docs adresine giderseniz, request'lerde gönderilecek ve response'larda alınacak veriler için schema'ları içerdiğini görürsünüz:

Bu schema'ları görebilirsiniz, çünkü uygulamada modellerle birlikte tanımlandılar.

Bu bilgi uygulamanın OpenAPI schema'sında bulunur ve sonrasında API dokümanlarında gösterilir.

OpenAPI'ye dahil edilen, modellerden gelen bu bilginin aynısı client code üretmek için kullanılabilir.

Hey API

Modelleri olan bir FastAPI uygulamamız olduğunda, Hey API ile bir TypeScript client üretebiliriz. Bunu yapmanın en hızlı yolu npx kullanmaktır.

npx @hey-api/openapi-ts -i http://localhost:8000/openapi.json -o src/client

Bu komut ./src/client içine bir TypeScript SDK üretecektir.

Web sitelerinde @hey-api/openapi-ts kurulumunu öğrenebilir ve üretilen çıktıyı inceleyebilirsiniz.

SDK'yı Kullanma

Artık client code'u import edip kullanabilirsiniz. Şuna benzer görünebilir; method'lar için otomatik tamamlama aldığınıza dikkat edin:

Ayrıca gönderilecek payload için de otomatik tamamlama alırsınız:

/// tip | İpucu

name ve price için otomatik tamamlamaya dikkat edin; bunlar FastAPI uygulamasında, Item modelinde tanımlanmıştı.

///

Gönderdiğiniz veriler için satır içi hatalar (inline errors) da alırsınız:

Response objesi de otomatik tamamlama sunacaktır:

Tag'lerle FastAPI Uygulaması

Birçok durumda FastAPI uygulamanız daha büyük olacaktır ve farklı path operation gruplarını ayırmak için muhtemelen tag'leri kullanacaksınız.

Örneğin items için bir bölüm, users için başka bir bölüm olabilir ve bunları tag'lerle ayırabilirsiniz:

{* ../../docs_src/generate_clients/tutorial002_py39.py hl[21,26,34] *}

Tag'lerle TypeScript Client Üretme

Tag'leri kullanan bir FastAPI uygulaması için client ürettiğinizde, genelde client code da tag'lere göre ayrılır.

Bu sayede client code tarafında her şey doğru şekilde sıralanır ve gruplandırılır:

Bu örnekte şunlar var:

  • ItemsService
  • UsersService

Client Method İsimleri

Şu an üretilen createItemItemsPost gibi method isimleri çok temiz görünmüyor:

ItemsService.createItemItemsPost({name: "Plumbus", price: 5})

...çünkü client üreteci, her path operation için OpenAPI'nin dahili operation ID değerini kullanır.

OpenAPI, her operation ID'nin tüm path operation'lar arasında benzersiz olmasını ister. Bu yüzden FastAPI; operation ID'yi benzersiz tutabilmek için function adı, path ve HTTP method/operation bilgilerini birleştirerek üretir.

Ancak bunu bir sonraki adımda nasıl iyileştirebileceğinizi göstereceğim. 🤓

Özel Operation ID'ler ve Daha İyi Method İsimleri

Bu operation ID'lerin üretilme şeklini değiştirerek, client'larda daha basit method isimleri elde edebilirsiniz.

Bu durumda, her operation ID'nin benzersiz olduğundan başka bir şekilde emin olmanız gerekir.

Örneğin, her path operation'ın bir tag'i olmasını sağlayabilir ve operation ID'yi tag ve path operation adına (function adı) göre üretebilirsiniz.

Benzersiz ID Üreten Özel Fonksiyon

FastAPI, her path operation için bir unique ID kullanır. Bu ID, operation ID için ve ayrıca request/response'lar için gerekebilecek özel model isimleri için de kullanılır.

Bu fonksiyonu özelleştirebilirsiniz. Bir APIRoute alır ve string döndürür.

Örneğin burada ilk tag'i (muhtemelen tek tag'iniz olur) ve path operation adını (function adı) kullanıyor.

Sonrasında bu özel fonksiyonu generate_unique_id_function parametresiyle FastAPI'ye geçebilirsiniz:

{* ../../docs_src/generate_clients/tutorial003_py39.py hl[6:7,10] *}

Özel Operation ID'lerle TypeScript Client Üretme

Artık client'ı tekrar üretirseniz, geliştirilmiş method isimlerini göreceksiniz:

Gördüğünüz gibi method isimleri artık önce tag'i, sonra function adını içeriyor; URL path'i ve HTTP operation bilgisini artık taşımıyor.

Client Üretecine Vermeden Önce OpenAPI Spesifikasyonunu Ön İşlemek

Üretilen kodda hâlâ bazı tekrarlanan bilgiler var.

Bu method'un items ile ilişkili olduğunu zaten biliyoruz; çünkü bu kelime ItemsService içinde var (tag'den geliyor). Ama method adında da tag adı önek olarak duruyor. 😕

OpenAPI genelinde muhtemelen bunu korumak isteriz; çünkü operation ID'lerin benzersiz olmasını sağlar.

Ancak üretilen client için, client'ları üretmeden hemen önce OpenAPI operation ID'lerini değiştirip, method isimlerini daha hoş ve temiz hale getirebiliriz.

OpenAPI JSON'u openapi.json diye bir dosyaya indirip, şu tarz bir script ile öndeki tag'i kaldırabiliriz:

{* ../../docs_src/generate_clients/tutorial004_py39.py *}

//// tab | Node.js

{!> ../../docs_src/generate_clients/tutorial004.js!}

////

Bununla operation ID'ler items-get_items gibi değerlerden sadece get_items olacak şekilde yeniden adlandırılır; böylece client üreteci daha basit method isimleri üretebilir.

Ön İşlenmiş OpenAPI ile TypeScript Client Üretme

Sonuç artık bir openapi.json dosyasında olduğuna göre, input konumunu güncellemeniz gerekir:

npx @hey-api/openapi-ts -i ./openapi.json -o src/client

Yeni client'ı ürettikten sonra, tüm otomatik tamamlama, satır içi hatalar, vb. ile birlikte temiz method isimleri elde edersiniz:

Faydalar

Otomatik üretilen client'ları kullanınca şu alanlarda otomatik tamamlama elde edersiniz:

  • Method'lar.
  • Body'deki request payload'ları, query parametreleri, vb.
  • Response payload'ları.

Ayrıca her şey için satır içi hatalar (inline errors) da olur.

Backend kodunu her güncellediğinizde ve frontend'i yeniden ürettiğinizde, yeni path operation'lar method olarak eklenir, eskileri kaldırılır ve diğer değişiklikler de üretilen koda yansır. 🤓

Bu, bir şey değiştiğinde client code'a otomatik olarak yansıyacağı anlamına gelir. Ayrıca client'ı build ettiğinizde, kullanılan verilerde bir uyuşmazlık (mismatch) varsa hata alırsınız.

Böylece üretimde son kullanıcılara hata yansımasını beklemek ve sonra sorunun nerede olduğunu debug etmeye çalışmak yerine, geliştirme sürecinin çok erken aşamalarında birçok hatayı tespit edersiniz. ✨