tiangolo.fastapi/docs/tr/docs/how-to/separate-openapi-schemas.md

Input ve Output için Ayrı OpenAPI Schema'ları (Ya da Değil)

Pydantic v2 yayınlandığından beri, üretilen OpenAPI eskisine göre biraz daha net ve doğru. 😎

Hatta bazı durumlarda, aynı Pydantic model için OpenAPI içinde input ve output tarafında, default değerler olup olmamasına bağlı olarak iki farklı JSON Schema bile görebilirsiniz.

Bunun nasıl çalıştığına ve gerekirse nasıl değiştirebileceğinize bir bakalım.

Input ve Output için Pydantic Modelleri

Default değerleri olan bir Pydantic modeliniz olduğunu varsayalım; örneğin şöyle:

{* ../../docs_src/separate_openapi_schemas/tutorial001_py310.py ln[1:7] hl[7] *}

Input için Model

Bu modeli şöyle input olarak kullanırsanız:

{* ../../docs_src/separate_openapi_schemas/tutorial001_py310.py ln[1:15] hl[14] *}

...description alanı zorunlu olmaz. Çünkü None default değerine sahiptir.

Dokümanlarda Input Modeli

Bunu dokümanlarda da doğrulayabilirsiniz; description alanında kırmızı yıldız yoktur, yani required olarak işaretlenmemiştir:

Output için Model

Ancak aynı modeli output olarak şöyle kullanırsanız:

{* ../../docs_src/separate_openapi_schemas/tutorial001_py310.py hl[19] *}

...description default değere sahip olduğu için, o alan için hiçbir şey döndürmeseniz bile yine de o default değeri alır.

Output Response Verisi için Model

Dokümanlarla etkileşip response'u kontrol ederseniz, kod description alanlarından birine bir şey eklememiş olsa bile, JSON response default değeri (null) içerir:

Bu, alanın her zaman bir değeri olacağı anlamına gelir; sadece bazen bu değer None olabilir (JSON'da null).

Dolayısıyla API'nizi kullanan client'ların bu değerin var olup olmadığını kontrol etmesine gerek yoktur; alanın her zaman mevcut olacağını varsayabilirler, sadece bazı durumlarda default değer olan None gelecektir.

Bunu OpenAPI'de ifade etmenin yolu, bu alanı required olarak işaretlemektir; çünkü her zaman yer alacaktır.

Bu nedenle, bir modelin JSON Schema'sı input mu output mu kullanıldığına göre farklı olabilir:

• input için description required olmaz
• output için required olur (ve None olabilir; JSON açısından null)

Dokümanlarda Output Modeli

Dokümanlarda output modelini de kontrol edebilirsiniz; hem name hem de description alanları kırmızı yıldız ile required olarak işaretlenmiştir:

Dokümanlarda Input ve Output Modelleri

OpenAPI içindeki tüm kullanılabilir Schema'lara (JSON Schema'lara) bakarsanız, iki tane olduğunu göreceksiniz: biri Item-Input, diğeri Item-Output.

Item-Input için description required değildir, kırmızı yıldız yoktur.

Ama Item-Output için description required'dır, kırmızı yıldız vardır.

Pydantic v2'nin bu özelliğiyle API dokümantasyonunuz daha hassas olur; ayrıca autogenerated client'lar ve SDK'lar kullanıyorsanız, onlar da daha tutarlı ve daha iyi bir developer experience ile daha doğru üretilir. 🎉

Schema'ları Ayırma

Bazı durumlarda input ve output için aynı schema'yı kullanmak isteyebilirsiniz.

Bunun muhtemelen en yaygın nedeni, halihazırda autogenerated client kodlarınız/SDK'larınızın olması ve henüz bunların hepsini güncellemek istememenizdir. Büyük ihtimalle bir noktada güncellemek isteyeceksiniz, ama belki şu an değil.

Bu durumda FastAPI'de bu özelliği separate_input_output_schemas=False parametresiyle kapatabilirsiniz.

/// info | Bilgi

separate_input_output_schemas desteği FastAPI 0.102.0 sürümünde eklendi. 🤓

///

{* ../../docs_src/separate_openapi_schemas/tutorial002_py310.py hl[10] *}

Dokümanlarda Input ve Output Modelleri için Aynı Schema

Artık model için input ve output tarafında tek bir schema olur: sadece Item. Ayrıca description alanı required değildir: