Şema ve security

Otomatik çıkarımın sınırlarını bilin ve özel request/response sözleşmelerini açıkça tanımlayın.

Typed action imzaları OpenAPI’nin çoğunu üretebilir. Ancak custom extractor, raw body veya özel response kullandığınızda belgeyi açık metadata ile tamamlamanız gerekir.

Otomatik çıkarım#

Typed path/query/header/body/multipart ve açık response wrapper’ları sözleşme üretiminde kullanılır. Result<String, E> JSON string, doğrudan String ise text yanıtıdır; runtime yanıt farkı OpenAPI’ye de yansır.

Açık metadata gereken durumlar#

Durum	Kontrol etmeniz gereken
Custom extractor	Parametre veya request body sözleşmesi
Raw body	Media type ve schema
Manual veya passthrough response	Status, header ve response şeması
Streaming, SSE veya static file	Media type ve özel response davranışı
Custom response converter	Başarı ve hata yanıtlarının gerçek gövdeleri

Bu yollar için parameters, request_body ve responses metadata’sını tanımlayın. ToResponse ve IntoResponses tekrar kullanılan yanıt sözleşmeleri içindir. Operation ID’leri kararlı ve benzersiz tutun; summary, description ve deprecated alanları açıklamayı tamamlar.

Security scheme#

OpenApiConfig::register_security_scheme ile bearer, API key veya OpenID Connect şeması kaydedebilirsiniz. Controller security metadata’sı action’lara miras kalır. Public bir action için boş security() açık override’dır.

Metadata doğrulama yapmaz. Security scheme belgedeki gerekliliği anlatır. Gerçek kimlik ve yetki kontrolünü #[guard(...)] ile uygulayın.

Build doğrulaması#

Duplicate operation ID/path/component, çözülemeyen reference ve security hataları build sırasında reddedilir. Standart dışı HTTP method için openapi(skip) gerekir; OpenAPI path-item method alanları dışında yeni alan varmış gibi davranılmaz.

Rehberdeki tam OpenAPI örneği bu kurulumun küçük başlangıcıdır. Her özel sözleşmeyi örnek istek/yanıtla karşılaştırarak güncel tutun.