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ünceldokümantasyon, birden fazla dilde istemci kütüphaneleri (SDKs) ve kodunuzla senkron kalantest veyaotomasyon iş akışları üretmek kolaylaşır.

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

Açık Kaynak SDK Üreteçleri¶

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

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

Daha fazla SDK üreteciniOpenAPI.Tools üzerinde keşfedebilirsiniz.

FastAPI Sponsorlarından SDK Üreteçleri¶

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

✨FastAPI'ye sponsor olarak ✨ bu şirketler, framework'ün veekosisteminin sağlıklı vesürdürülebilir kalmasına yardımcı olur.

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

Örneğin şunları deneyebilirsiniz:

• Speakeasy
• Stainless
• liblab

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:

fromfastapiimportFastAPIfrompydanticimportBaseModelapp=FastAPI()classItem(BaseModel):name:strprice:floatclassResponseMessage(BaseModel):message:str@app.post("/items/",response_model=ResponseMessage)asyncdefcreate_item(item:Item):return{"message":"item received"}@app.get("/items/",response_model=list[Item])asyncdefget_items():return[{"name":"Plumbus","price":3},{"name":"Portal Gun","price":9001},]

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

API Dokümanları¶

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

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

Bu bilgi uygulamanınOpenAPI 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-ihttp://localhost:8000/openapi.json-osrc/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:

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ğinitems için bir bölüm,users için başka bir bölüm olabilir ve bunları tag'lerle ayırabilirsiniz:

fromfastapiimportFastAPIfrompydanticimportBaseModelapp=FastAPI()classItem(BaseModel):name:strprice:floatclassResponseMessage(BaseModel):message:strclassUser(BaseModel):username:stremail:str@app.post("/items/",response_model=ResponseMessage,tags=["items"])asyncdefcreate_item(item:Item):return{"message":"Item received"}@app.get("/items/",response_model=list[Item],tags=["items"])asyncdefget_items():return[{"name":"Plumbus","price":3},{"name":"Portal Gun","price":9001},]@app.post("/users/",response_model=ResponseMessage,tags=["users"])asyncdefcreate_user(user:User):return{"message":"User received"}

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 üretilencreateItemItemsPost gibi method isimleri çok temiz görünmüyor:

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

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

OpenAPI, her operation ID'nin tümpath operation'lar arasında benzersiz olmasını ister. Bu yüzden FastAPI; operation ID'yi benzersiz tutabilmek içinfunction adı,path veHTTP 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 şeklinideğiştirerek, client'larda daha basitmethod isimleri elde edebilirsiniz.

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

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

Benzersiz ID Üreten Özel Fonksiyon¶

FastAPI, herpath operation için birunique 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. BirAPIRoute alır ve string döndürür.

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

Sonrasında bu özel fonksiyonugenerate_unique_id_function parametresiyleFastAPI'ye geçebilirsiniz:

fromfastapiimportFastAPIfromfastapi.routingimportAPIRoutefrompydanticimportBaseModeldefcustom_generate_unique_id(route:APIRoute):returnf"{route.tags[0]}-{route.name}"app=FastAPI(generate_unique_id_function=custom_generate_unique_id)classItem(BaseModel):name:strprice:floatclassResponseMessage(BaseModel):message:strclassUser(BaseModel):username:stremail:str@app.post("/items/",response_model=ResponseMessage,tags=["items"])asyncdefcreate_item(item:Item):return{"message":"Item received"}@app.get("/items/",response_model=list[Item],tags=["items"])asyncdefget_items():return[{"name":"Plumbus","price":3},{"name":"Portal Gun","price":9001},]@app.post("/users/",response_model=ResponseMessage,tags=["users"])asyncdefcreate_user(user:User):return{"message":"User received"}

Ö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'unitems ile ilişkili olduğunu zaten biliyoruz; çünkü bu kelimeItemsService 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'lerinbenzersiz olmasını sağlar.

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

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

importjsonfrompathlibimportPathfile_path=Path("./openapi.json")openapi_content=json.loads(file_path.read_text())forpath_datainopenapi_content["paths"].values():foroperationinpath_data.values():tag=operation["tags"][0]operation_id=operation["operationId"]to_remove=f"{tag}-"new_operation_id=operation_id[len(to_remove):]operation["operationId"]=new_operation_idfile_path.write_text(json.dumps(openapi_content))

import*asfsfrom'fs'asyncfunctionmodifyOpenAPIFile(filePath){try{constdata=awaitfs.promises.readFile(filePath)constopenapiContent=JSON.parse(data)constpaths=openapiContent.pathsfor(constpathKeyofObject.keys(paths)){constpathData=paths[pathKey]for(constmethodofObject.keys(pathData)){constoperation=pathData[method]if(operation.tags&&operation.tags.length>0){consttag=operation.tags[0]constoperationId=operation.operationIdconsttoRemove=`${tag}-`if(operationId.startsWith(toRemove)){constnewOperationId=operationId.substring(toRemove.length)operation.operationId=newOperationId}}}}awaitfs.promises.writeFile(filePath,JSON.stringify(openapiContent,null,2),)console.log('File successfully modified')}catch(err){console.error('Error:',err)}}constfilePath='./openapi.json'modifyOpenAPIFile(filePath)

Bununla operation ID'leritems-get_items gibi değerlerden sadeceget_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 biropenapi.json dosyasında olduğuna göre, input konumunu güncellemeniz gerekir:

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

Yeni client'ı ürettikten sonra, tümotomatik tamamlama,satır içi hatalar, vb. ile birliktetemiz method isimleri elde edersiniz:

Faydalar¶

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

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

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

Backend kodunu her güncellediğinizde ve frontend'iyeniden ürettiğinizde, yenipath 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 olarakyansıyacağı anlamına gelir. Ayrıca client'ıbuild ettiğinizde, kullanılan verilerde biruyuş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ındabirçok hatayı tespit edersiniz. ✨