\n .NET 9’un geli\u015ftirici \u00f6nizleme s\u00fcr\u00fcmleriyle birlikte dikkat \u00e7eken \u00f6nemli bir de\u011fi\u015fiklik, varsay\u0131lan web API \u015fablonlar\u0131ndan pop\u00fcler Swagger\/OpenAPI belgeleme k\u00fct\u00fcphanesi Swashbuckle’\u0131n \u00e7\u0131kar\u0131lmas\u0131 oldu. Bu durum, uzun s\u00fcredir Swashbuckle kullanan bir\u00e7ok geli\u015ftirici i\u00e7in ba\u015flang\u0131\u00e7ta kafa kar\u0131\u015ft\u0131r\u0131c\u0131 olsa da, asl\u0131nda Microsoft’un .NET ekosisteminde API belgelemesine y\u00f6nelik daha entegre ve modern bir yakla\u015f\u0131m\u0131n sinyalini veriyor. Peki, bu de\u011fi\u015fiklik ne anlama geliyor ve API’lerinizin etkile\u015fimli Swagger UI belgelemesini kaybetmeden .NET 9’a nas\u0131l adapte olabilirsiniz? Bu makalede, .NET 9’un yeni belgeleme stratejisini derinlemesine inceleyecek, Swashbuckle olmadan Swagger UI’\u0131 projelerinize nas\u0131l entegre edece\u011finizi ad\u0131m ad\u0131m g\u00f6sterecek ve en iyi uygulamalarla API geli\u015ftirme s\u00fcre\u00e7lerinizi g\u00fc\u00e7lendirece\u011fiz. Amac\u0131m\u0131z, ge\u00e7i\u015fi sorunsuz hale getirmek ve gelece\u011fe d\u00f6n\u00fck, s\u00fcrd\u00fcr\u00fclebilir bir API belgeleme \u00e7\u00f6z\u00fcm\u00fc sunmakt\u0131r.\n<\/p>\n
\n Uzun y\u0131llard\u0131r ASP.NET Core API projelerinin vazge\u00e7ilmez bir par\u00e7as\u0131 olan Swashbuckle, geli\u015ftiricilerin RESTful API’leri i\u00e7in OpenAPI (eski ad\u0131yla Swagger) belgeleri olu\u015fturmas\u0131n\u0131 ve bunlar\u0131 etkile\u015fimli Swagger UI aray\u00fcz\u00fcnde sunmas\u0131n\u0131 sa\u011flayan g\u00fc\u00e7l\u00fc bir k\u00fct\u00fcphaneydi. Basitli\u011fi ve geni\u015f \u00f6zelle\u015ftirme se\u00e7enekleri sayesinde, API’lerin belgelenmesi ve ke\u015ffedilmesi s\u00fcre\u00e7lerini \u00f6nemli \u00f6l\u00e7\u00fcde h\u0131zland\u0131rd\u0131. Ancak, .NET ekosistemi s\u00fcrekli evrim ge\u00e7irirken, Microsoft da platformun temel yeteneklerini geli\u015ftirerek d\u0131\u015f ba\u011f\u0131ml\u0131l\u0131klar\u0131 azaltma ve daha b\u00fct\u00fcnle\u015fik \u00e7\u00f6z\u00fcmler sunma e\u011filiminde. .NET 9’da Swashbuckle’\u0131n varsay\u0131lan \u015fablonlardan \u00e7\u0131kar\u0131lmas\u0131, bu stratejik y\u00f6nelimin bir yans\u0131mas\u0131 olarak ortaya \u00e7\u0131kt\u0131. Bu hamle, bir\u00e7ok geli\u015ftiricinin ilk ba\u015fta bir kay\u0131p gibi alg\u0131lamas\u0131na neden olsa da, asl\u0131nda .NET’in yerle\u015fik OpenAPI yeteneklerinin art\u0131k yeterince olgunla\u015ft\u0131\u011f\u0131n\u0131 ve hatta belirli senaryolarda Swashbuckle’a alternatif olabilece\u011fini g\u00f6steriyor.\n<\/p>\n
\n Peki, Swashbuckle’\u0131n kald\u0131r\u0131lmas\u0131 tam olarak ne anlama geliyor? \u00d6ncelikle, Swashbuckle’\u0131n tamamen “\u00f6lmedi\u011fini” vurgulamak gerekir. K\u00fct\u00fcphane hala mevcut ve .NET 9 projelerinde manuel olarak eklenebilir. Ancak, .NET 9 ve sonraki s\u00fcr\u00fcmlerde API belgelemesi i\u00e7in Microsoft’un tercih etti\u011fi yol, platformun kendi b\u00fcnyesindeki OpenAPI entegrasyonu ve Minimal API’ler gibi yeni nesil yakla\u015f\u0131mlarla daha s\u0131k\u0131 bir uyum i\u00e7inde olmak. Microsoft, \u00f6zellikle Minimal API’ler i\u00e7in tip tabanl\u0131 OpenAPI deste\u011fini g\u00fc\u00e7lendirerek, geli\u015ftiricilerin kodlar\u0131na do\u011frudan yans\u0131yan, daha az “boilerplate” kodu gerektiren bir belgeleme deneyimi sunmay\u0131 hedefliyor. Bu, API tan\u0131mlar\u0131n\u0131n do\u011frudan C# kodundan t\u00fcretilerek g\u00fcncelli\u011fini korumas\u0131n\u0131 kolayla\u015ft\u0131r\u0131yor ve belgeleme s\u00fcrecini daha “do\u011fal” hale getiriyor.\n<\/p>\n
\n Bu stratejik de\u011fi\u015fiklik, geli\u015ftiricilere daha yal\u0131n ve optimize edilmi\u015f bir API geli\u015ftirme ve belgeleme s\u00fcreci vaat ediyor. Daha az \u00fc\u00e7\u00fcnc\u00fc taraf ba\u011f\u0131ml\u0131l\u0131\u011f\u0131, potansiyel olarak daha az yap\u0131land\u0131rma karma\u015fas\u0131 ve gelecekteki .NET s\u00fcr\u00fcmleriyle daha iyi entegrasyon anlam\u0131na gelebilir. Ayr\u0131ca, bu durum .NET geli\u015ftiricilerini OpenAPI Specification (OAS) standartlar\u0131n\u0131 daha derinden anlamaya ve belgeleme s\u00fcre\u00e7lerini daha bilin\u00e7li bir \u015fekilde y\u00f6netmeye te\u015fvik ediyor. Her ne kadar ilk ba\u015fta bir al\u0131\u015fma s\u00fcreci gerektirse de, uzun vadede daha sa\u011flam, bak\u0131m\u0131 kolay ve performansl\u0131 API projeleri in\u015fa etmemize yard\u0131mc\u0131 olacak bir ad\u0131m olarak g\u00f6r\u00fclebilir. Bu b\u00f6l\u00fcm\u00fcn devam\u0131nda, OpenAPI ve Swagger UI gibi temel kavramlar\u0131 daha yak\u0131ndan inceleyecek ve .NET 9’un bu konudaki yeni yakla\u015f\u0131mlar\u0131na de\u011finece\u011fiz. B\u00f6ylece, bu de\u011fi\u015fimin ard\u0131ndaki mant\u0131\u011f\u0131 tam olarak kavrayabilir ve kendi projelerinizde do\u011fru kararlar\u0131 alabilirsiniz.\n<\/p>\n
\n API belgeleme d\u00fcnyas\u0131nda s\u0131k\u00e7a kar\u0131\u015ft\u0131r\u0131lan ancak kritik farkl\u0131l\u0131klara sahip \u00fc\u00e7 temel kavram vard\u0131r: OpenAPI Specification (OAS), Swagger UI ve Swashbuckle. .NET 9’daki de\u011fi\u015fiklikleri tam olarak anlayabilmek i\u00e7in bu kavramlar\u0131n her birinin ne anlama geldi\u011fini ve birbirleriyle nas\u0131l ili\u015fkilendi\u011fini netle\u015ftirmek hayati \u00f6nem ta\u015f\u0131r. \u00d6ncelikle, temelleri sa\u011flam bir \u015fekilde oturtal\u0131m.\n<\/p>\n
\n OpenAPI Specification (OAS)<\/strong>, RESTful API’ler i\u00e7in dilagnostik ve makine taraf\u0131ndan okunabilir bir aray\u00fcz tan\u0131mlama standard\u0131d\u0131r. Bir nevi API’nizin “kontrat\u0131n\u0131” veya “mimar plan\u0131n\u0131” JSON veya YAML format\u0131nda a\u00e7\u0131klayan bir \u015femad\u0131r. OAS, API’nin hangi endpoint’lere sahip oldu\u011funu, bu endpoint’lerin hangi HTTP metotlar\u0131n\u0131 destekledi\u011fini (GET, POST, PUT, DELETE vb.), hangi parametreleri bekledi\u011fini (URL yolu, sorgu dizesi, ba\u015fl\u0131k, g\u00f6vde), hangi veri tiplerini d\u00f6nd\u00fcrece\u011fini ve olas\u0131 hata yan\u0131tlar\u0131n\u0131 detayland\u0131r\u0131r. Bir API’nin t\u00fcm yeteneklerini standartla\u015ft\u0131r\u0131lm\u0131\u015f bir \u015fekilde belgelemeyi ama\u00e7lar. Bu standardizasyon, farkl\u0131 programlama dilleri ve platformlar aras\u0131nda API’lerin kolayca ke\u015ffedilmesini, anla\u015f\u0131lmas\u0131n\u0131 ve t\u00fcketilmesini sa\u011flar. Bir OAS belgesi, kod \u00fcretiminden (client SDK’lar\u0131, sunucu iskeletleri), test ara\u00e7lar\u0131na ve etkile\u015fimli belgeleme aray\u00fczlerine kadar bir\u00e7ok farkl\u0131 ara\u00e7 taraf\u0131ndan kullan\u0131labilir.\n<\/p>\n \n Swagger UI<\/strong>, OpenAPI Specification belgelerini g\u00f6rselle\u015ftiren, etkile\u015fimli ve web tabanl\u0131 bir ara\u00e7t\u0131r. Bir OAS belgesini (genellikle bir JSON dosyas\u0131 olarak sunulur) al\u0131r ve bunu insan taraf\u0131ndan kolayca okunabilen, ke\u015ffedilebilir bir aray\u00fcze d\u00f6n\u00fc\u015ft\u00fcr\u00fcr. Swagger UI sayesinde geli\u015ftiriciler ve API t\u00fcketicileri, API’nin t\u00fcm endpoint’lerini, parametrelerini ve \u00f6rnek yan\u0131tlar\u0131n\u0131 tek bir web sayfas\u0131nda g\u00f6rebilirler. Dahas\u0131, Swagger UI sadece pasif bir belge g\u00f6r\u00fcnt\u00fcleyici de\u011fildir; API endpoint’lerine do\u011frudan web aray\u00fcz\u00fcnden istek g\u00f6ndermenize ve yan\u0131tlar\u0131 ger\u00e7ek zamanl\u0131 olarak g\u00f6rmenize olanak tan\u0131r. Bu “deneyin” \u00f6zelli\u011fi, API’nin nas\u0131l \u00e7al\u0131\u015ft\u0131\u011f\u0131n\u0131 anlamak ve test etmek i\u00e7in paha bi\u00e7ilmez bir kolayl\u0131k sunar. Swagger UI’\u0131n kendisi bir JavaScript k\u00fct\u00fcphanesidir ve herhangi bir web uygulamas\u0131na entegre edilebilir.\n<\/p>\n \n Swashbuckle.AspNetCore<\/strong> ise, ASP.NET Core uygulamalar\u0131 i\u00e7in \u00f6zel olarak geli\u015ftirilmi\u015f pop\u00fcler bir NuGet paketidir. Temel g\u00f6revi, ASP.NET Core API’lerinizdeki C# kodunu tarayarak otomatik olarak bir OpenAPI Specification belgesi (Swagger JSON) olu\u015fturmakt\u0131r. Ayr\u0131ca, bu otomatik olarak olu\u015fturulan belgenin sunulmas\u0131 i\u00e7in Swagger UI’\u0131 uygulaman\u0131za entegre eder. Yani Swashbuckle, kodu OpenAPI’ye d\u00f6n\u00fc\u015ft\u00fcrme ve Swagger UI’\u0131 yay\u0131nlama g\u00f6revlerini bir araya getiren bir k\u00f6pr\u00fc g\u00f6revi g\u00f6r\u00fcr. Geli\u015ftiricilerin elle OpenAPI belgesi yazma zahmetinden kurtulmas\u0131n\u0131 ve kod de\u011fi\u015fiklikleriyle belgelerin otomatik olarak g\u00fcncel kalmas\u0131n\u0131 sa\u011flar. \u0130\u00e7erisinde \n \u00d6zetle:\n<\/p>\n \n Bu ayr\u0131mlar\u0131 anlad\u0131ktan sonra, .NET 9’un Swashbuckle’\u0131 kald\u0131rmas\u0131n\u0131n asl\u0131nda API belgeleme yetene\u011fini kaybetmek de\u011fil, bu yetene\u011fi farkl\u0131 bir yolla, genellikle daha yerel ve entegre bir bi\u00e7imde sa\u011flamak oldu\u011fu anla\u015f\u0131lacakt\u0131r. Bir sonraki b\u00f6l\u00fcmde, .NET 9’un bu yeni yerel belgeleme stratejilerini ve Microsoft’un bu konudaki genel y\u00f6nelimini detayland\u0131raca\u011f\u0131z.\n<\/p>\n \n .NET 9 ile birlikte Microsoft, API belgeleme konusunda daha entegre ve “\u00fcr\u00fcn i\u00e7i” \u00e7\u00f6z\u00fcmlere odaklanarak geli\u015ftirici deneyimini basitle\u015ftirmeyi hedefliyor. Bu yeni stratejinin temelinde, OpenAPI Specification’\u0131n (OAS) do\u011frudan platformun i\u00e7ine derinlemesine entegrasyonu yat\u0131yor. Daha \u00f6nceki .NET Core s\u00fcr\u00fcmlerinde de baz\u0131 temel OpenAPI yetenekleri bulunsa da, .NET 9 ile bu yetenekler \u00f6zellikle Minimal API’ler ba\u011flam\u0131nda \u00f6nemli \u00f6l\u00e7\u00fcde g\u00fc\u00e7lendirildi ve geli\u015ftirildi. Microsoft’un bu y\u00f6ndeki ad\u0131mlar\u0131, geli\u015ftiricilerin \u00fc\u00e7\u00fcnc\u00fc taraf k\u00fct\u00fcphanelere olan ba\u011f\u0131ml\u0131l\u0131klar\u0131n\u0131 azaltarak, daha tutarl\u0131 ve s\u00fcrd\u00fcr\u00fclebilir bir API geli\u015ftirme ve belgeleme i\u015f ak\u0131\u015f\u0131 sunma amac\u0131 ta\u015f\u0131yor.\n<\/p>\n \n Bu yeni stratejinin en belirgin \u00f6zelliklerinden biri, \n \n Microsoft’un bu stratejisi, sadece mevcut API’lerin belgelenmesini kolayla\u015ft\u0131rmakla kalm\u0131yor, ayn\u0131 zamanda yeni ortaya \u00e7\u0131kan konseptlerle de uyum sa\u011fl\u0131yor. \u00d6rne\u011fin, .NET Aspire gibi bulut tabanl\u0131 uygulamalar geli\u015ftirmeyi hedefleyen yeni platformlarda, API’lerin ke\u015ffedilebilirli\u011fi ve otomatik belgelenmesi kritik bir rol oynuyor. .NET 9’daki bu yerel OpenAPI deste\u011fi, Aspire gibi platformlarla sorunsuz entegrasyon i\u00e7in sa\u011flam bir temel olu\u015fturuyor. Geli\u015ftiriciler, daha az \u00fc\u00e7\u00fcnc\u00fc taraf ba\u011f\u0131ml\u0131l\u0131\u011f\u0131yla \u00e7al\u0131\u015farak projelerinin karma\u015f\u0131kl\u0131\u011f\u0131n\u0131 azaltabilir ve platformun sundu\u011fu yerle\u015fik ara\u00e7lardan maksimum verim alabilirler.\n<\/p>\n \n \u00d6te yandan, mevcut Swashbuckle kullan\u0131c\u0131lar\u0131 i\u00e7in bu ge\u00e7i\u015fin baz\u0131 adaptasyon s\u00fcre\u00e7leri olabilece\u011fi a\u015fikard\u0131r. \u00d6zellikle karma\u015f\u0131k \u00f6zelle\u015ftirmelere veya \u00f6zel Swagger filtrelerine sahip projelerde, yerel OpenAPI entegrasyonuna ge\u00e7i\u015f biraz daha fazla efor gerektirebilir. Ancak genel itibar\u0131yla, Microsoft’un bu yeni belgeleme stratejisi, .NET API geli\u015ftiricileri i\u00e7in daha basit, daha entegre ve gelece\u011fe d\u00f6n\u00fck bir yol \u00e7iziyor. Sonraki b\u00f6l\u00fcmde, bu yeni yakla\u015f\u0131m\u0131 pratik bir \u015fekilde nas\u0131l uygulayaca\u011f\u0131n\u0131z\u0131 ad\u0131m ad\u0131m g\u00f6sterecek ve kod \u00f6rnekleriyle konuyu somutla\u015ft\u0131raca\u011f\u0131z. B\u00f6ylece, .NET 9’da Swashbuckle olmadan Swagger UI’\u0131 nas\u0131l hayata ge\u00e7irebilece\u011finizi net bir \u015fekilde g\u00f6rebileceksiniz.\n<\/p>\n \n .NET 9’a ge\u00e7erken veya yeni bir .NET 9 projesi ba\u015flat\u0131rken, Swashbuckle ba\u011f\u0131ml\u0131l\u0131\u011f\u0131ndan kurtulup Microsoft’un yerel OpenAPI entegrasyonunu ve Swagger UI’\u0131 nas\u0131l kullanaca\u011f\u0131n\u0131z\u0131 \u00f6\u011frenmek, modern API geli\u015ftirme pratiklerinin \u00f6nemli bir par\u00e7as\u0131d\u0131r. Bu b\u00f6l\u00fcmde, hem varolan bir projeyi g\u00fcncelleme hem de s\u0131f\u0131rdan yeni bir proje olu\u015fturma senaryolar\u0131 i\u00e7in ad\u0131m ad\u0131m rehberlik sunaca\u011f\u0131z.\n<\/p>\n \n E\u011fer .NET 6 veya .NET 7 gibi \u00f6nceki s\u00fcr\u00fcmlerden .NET 9’a y\u00fckseltti\u011finiz bir projeniz varsa ve bu projede Swashbuckle kullan\u0131yorsan\u0131z, ge\u00e7i\u015f s\u00fcreci biraz dikkat gerektirebilir. \u0130lk ad\u0131m, projenizin hedef framework’\u00fcn\u00fc <\/code><\/p>\n \n Ard\u0131ndan, \n \u015eimdi, en yayg\u0131n senaryo olan yeni bir .NET 9 Minimal API projesi olu\u015fturarak s\u00fcreci ad\u0131m ad\u0131m inceleyelim.\n<\/p>\n <\/code> <\/code> <\/code><\/p>\n \n Yukar\u0131daki kodda, <\/code> \n G\u00f6rd\u00fc\u011f\u00fcn\u00fcz gibi, Swashbuckle olmadan da .NET 9 projelerinizde tam i\u015flevsel bir Swagger UI deneyimi olu\u015fturmak olduk\u00e7a basittir. Microsoft'un yerel entegrasyonu, daha az ba\u011f\u0131ml\u0131l\u0131kla ve daha do\u011frudan bir yakla\u015f\u0131mla API belgelemenizi sa\u011flar. Bu y\u00f6ntem, \u00f6zellikle Minimal API'lerin sadeli\u011fiyle \u00e7ok iyi uyum sa\u011flar ve gelecekteki .NET s\u00fcr\u00fcmlerinde API belgeleme i\u00e7in standart yakla\u015f\u0131m olmaya adayd\u0131r. Sonraki b\u00f6l\u00fcmde, bu yakla\u015f\u0131mlar\u0131 b\u00fcy\u00fck \u00f6l\u00e7ekli bir kurumsal API senaryosunda nas\u0131l uygulayabilece\u011fimize dair bir vaka analizine odaklanaca\u011f\u0131z.\n<\/p>\n \n Bir\u00e7ok kurumsal uygulama, zamanla b\u00fcy\u00fcyen ve karma\u015f\u0131kla\u015fan API setlerine sahiptir. Bu API'ler genellikle birden fazla ekip taraf\u0131ndan geli\u015ftirilir, farkl\u0131 servisleri bir araya getirir ve uzun s\u00fcredir \u00fcretimde olan projelerdir. B\u00f6yle bir projenin .NET 9'a ge\u00e7i\u015fi ve API belgeleme stratejisinin g\u00fcncellenmesi, sadece kod de\u011fi\u015fikliklerinden ibaret olmayan, ayn\u0131 zamanda mimari ve s\u00fcre\u00e7sel kararlar\u0131 da i\u00e7eren kapsaml\u0131 bir s\u00fcre\u00e7tir. Bu vaka analizinde, \"TechCorp\" adl\u0131 hayali bir \u015firketin, eski bir .NET 7 tabanl\u0131 e-ticaret mikroservis API'sini .NET 9'a ta\u015f\u0131ma ve Swashbuckle ba\u011f\u0131ml\u0131l\u0131\u011f\u0131ndan kurtulma hikayesini inceleyece\u011fiz.\n<\/p>\n \n TechCorp'un ana API'si, \u00fcr\u00fcn katalog y\u00f6netimi, kullan\u0131c\u0131 profilleri, sipari\u015f i\u015fleme ve \u00f6deme entegrasyonlar\u0131 gibi bir\u00e7ok farkl\u0131 mikroservisi y\u00f6neten bir Gateway API'ydi. Bu API, .NET 7 \u00fczerinde geli\u015ftirilmi\u015f olup, t\u00fcm belgeleme s\u00fcre\u00e7leri Swashbuckle.AspNetCore paketi \u00fczerinden y\u00f6netiliyordu. Proje b\u00fcy\u00fcd\u00fck\u00e7e, Swashbuckle'\u0131n sundu\u011fu esneklik takdir edilse de, ba\u011f\u0131ml\u0131l\u0131k g\u00fcncellemeleri, bazen karma\u015f\u0131k \u00f6zelle\u015ftirmelerin getirdi\u011fi performans y\u00fckleri ve .NET'in kendi i\u00e7inde geli\u015fen yeteneklerle \u00e7ak\u0131\u015fmalar gibi k\u00fc\u00e7\u00fck sorunlar ya\u015fan\u0131yordu. \u00d6zellikle, ekip yeni Minimal API'ler ve gRPC gibi teknolojilere y\u00f6neldik\u00e7e, belgeleme stratejisinde daha hafif ve entegre bir \u00e7\u00f6z\u00fcm aray\u0131\u015f\u0131 do\u011fmu\u015ftu.\n<\/p>\n \n TechCorp ekibi, .NET 9'a ge\u00e7i\u015fi sadece bir versiyon y\u00fckseltmesi olarak de\u011fil, ayn\u0131 zamanda API belgeleme stratejilerini modernize etme f\u0131rsat\u0131 olarak g\u00f6rd\u00fc. A\u015fa\u011f\u0131daki ad\u0131mlar izlendi:\n<\/p>\n <\/code>\n <\/li>\nSwashbuckle.AspNetCore.Swagger<\/code>, Swashbuckle.AspNetCore.SwaggerGen<\/code> ve Swashbuckle.AspNetCore.SwaggerUI<\/code> gibi farkl\u0131 bile\u015fenler bar\u0131nd\u0131r\u0131r. .NET 9’da \u015fablonlardan \u00e7\u0131kar\u0131lmas\u0131na ra\u011fmen, .NET 9 uygulamalar\u0131na manuel olarak eklenebilir ve \u00e7al\u0131\u015fmaya devam edebilir. Ancak, Microsoft’un yerel OpenAPI deste\u011fi, Swashbuckle’\u0131n sundu\u011fu otomasyonun bir k\u0131sm\u0131n\u0131 kendi b\u00fcnyesine katm\u0131\u015ft\u0131r.\n<\/p>\n\n
.NET 9 ve API Belgeleme Stratejisi: Yeni Nesil Yakla\u015f\u0131mlar ve Microsoft’un Y\u00f6n\u00fc<\/h2>\n
Microsoft.AspNetCore.OpenApi<\/code> NuGet paketinin ve .NET 9 \u015fablonlar\u0131nda varsay\u0131lan olarak gelen ilgili yap\u0131land\u0131rmalar\u0131n artan \u00f6nemi. Bu paket, API’nizin endpoint’lerini, parametrelerini ve yan\u0131t tiplerini kodunuzdan otomatik olarak t\u00fcreterek standart bir OpenAPI belgesi olu\u015fturma yetene\u011fini temel bir bile\u015fen olarak sunar. \u00d6zellikle Minimal API’lerde, rotalar\u0131n ve i\u015fleyici fonksiyonlar\u0131n\u0131n tan\u0131m\u0131ndan yola \u00e7\u0131karak OpenAPI \u015femas\u0131n\u0131 olu\u015fturmak art\u0131k \u00e7ok daha do\u011fal ve kolay. \u00d6rne\u011fin, bir Minimal API’de bir parametrenin tipi veya bir d\u00f6n\u00fc\u015f de\u011feri, do\u011frudan OpenAPI belgesine yans\u0131r. Bu “tip tabanl\u0131 OpenAPI” yakla\u015f\u0131m\u0131, belgelerin her zaman kodla senkronize kalmas\u0131n\u0131 sa\u011fl\u0131yor, ki bu da manuel belge g\u00fcncellemelerinin neden oldu\u011fu tutars\u0131zl\u0131klar\u0131 b\u00fcy\u00fck \u00f6l\u00e7\u00fcde ortadan kald\u0131r\u0131yor.\n<\/p>\nAddOpenApiDocument()<\/code> metodu ve MapSwagger()<\/code> veya UseSwaggerUI()<\/code> uzant\u0131 metotlar\u0131, bu yeni stratejinin merkezinde yer al\u0131yor. AddOpenApiDocument()<\/code> metodu, uygulaman\u0131z\u0131n servislere OpenAPI dok\u00fcman\u0131 olu\u015fturma yetene\u011fini eklerken, UseSwaggerUI()<\/code> ise bu dok\u00fcman\u0131 taray\u0131c\u0131da g\u00f6rselle\u015ftirmek i\u00e7in Swagger UI’\u0131 etkinle\u015ftiriyor. \u00d6nemli olan, bu bile\u015fenlerin art\u0131k .NET ekosisteminin birinci s\u0131n\u0131f vatanda\u015flar\u0131 olarak kabul edilmesi ve Microsoft taraf\u0131ndan do\u011frudan desteklenmesidir. Bu durum, gelecekteki .NET g\u00fcncellemeleriyle uyumlulu\u011fun ve performans optimizasyonlar\u0131n\u0131n daha iyi olaca\u011f\u0131 anlam\u0131na geliyor. Ayr\u0131ca, Minimal API’lerin getirdi\u011fi sadele\u015ftirilmi\u015f yap\u0131, belgeleme kodunun da daha okunabilir ve y\u00f6netilebilir olmas\u0131n\u0131 sa\u011fl\u0131yor.\n<\/p>\nAd\u0131m Ad\u0131m Uygulama: .NET 9 Projelerinizde Swashbuckle Olmadan Swagger UI Kurulumu<\/h2>\n
Varolan Projeyi .NET 9’a G\u00fcncellemek ve Swashbuckle’dan Ayr\u0131lmak<\/h3>\n
.NET 9<\/code> olarak g\u00fcncellemek olacakt\u0131r. Daha sonra, csproj<\/code> dosyan\u0131zdaki Swashbuckle paketlerini (genellikle Swashbuckle.AspNetCore<\/code> veya ilgili alt paketleri) kald\u0131rman\u0131z gerekecektir.\n<\/p>\n\n\n\n<\/pre>\nProgram.cs<\/code> dosyan\u0131zda Swashbuckle ile ilgili t\u00fcm yap\u0131land\u0131rma kodlar\u0131n\u0131 (AddSwaggerGen<\/code>, UseSwagger<\/code>, UseSwaggerUI<\/code> metodlar\u0131 ve varsa custom Swagger filtreleri) kald\u0131rmal\u0131s\u0131n\u0131z. Bu temizlik, projenizi Microsoft'un native OpenAPI deste\u011fine haz\u0131rlayacakt\u0131r. E\u011fer Minimal API'ler yerine geleneksel Controller tabanl\u0131 API'ler kullan\u0131yorsan\u0131z, Microsoft.AspNetCore.OpenApi<\/code> paketini eklemeniz gerekebilir.\n<\/p>\nYeni Bir .NET 9 Projesinde Swagger UI'\u0131 S\u0131f\u0131rdan Kurmak<\/h3>\n
\n
\n Komut sat\u0131r\u0131n\u0131 a\u00e7\u0131n ve yeni bir .NET Web API projesi olu\u015fturun.<\/p>\n\ndotnet new web -n MyOpenApiApp --output MyOpenApiApp\ncd MyOpenApiApp\n <\/pre>\n
\n Bu komut, Minimal API'leri kullanan yeni bir proje olu\u015fturacakt\u0131r. .NET 9 \u015fablonlar\u0131 art\u0131k varsay\u0131lan olarak Swashbuckle i\u00e7ermedi\u011fi i\u00e7in, proje ba\u015flang\u0131\u00e7ta Swagger UI'dan yoksun olacakt\u0131r.\n <\/li>\n
\n Microsoft'un yerel OpenAPI deste\u011fini kullanmak i\u00e7in Microsoft.AspNetCore.OpenApi<\/code> paketini eklemelisiniz. Bu paket, OpenAPI belgelerini olu\u015fturmak i\u00e7in gerekli altyap\u0131y\u0131 sa\u011flar.<\/p>\n\ndotnet add package Microsoft.AspNetCore.OpenApi\n <\/pre>\n
\n Bu paket, hem belgeleme \u015femas\u0131n\u0131 \u00fcretmenize yard\u0131mc\u0131 olur hem de Swagger UI'\u0131 uygulaman\u0131za dahil etmek i\u00e7in gerekli entegrasyonlar\u0131 i\u00e7erir.\n <\/li>\nProgram.cs<\/code> Dosyas\u0131n\u0131 Yap\u0131land\u0131rma:<\/strong>
\n \u015eimdi, Program.cs<\/code> dosyan\u0131z\u0131 a\u00e7\u0131n ve a\u015fa\u011f\u0131daki kod bloklar\u0131n\u0131 ekleyin veya mevcut Minimal API tan\u0131mlamalar\u0131n\u0131z\u0131 g\u00fcncelleyin.<\/p>\n\nvar builder = WebApplication.CreateBuilder(args);\n\n\/\/ Learn more about configuring Swagger\/OpenAPI at https:\/\/aka.ms\/aspnetcore\/swashbuckle\n\/\/ 1. OpenAPI belgeleme servislerini ekle\nbuilder.Services.AddEndpointsApiExplorer();\nbuilder.Services.AddSwaggerGen(); \/\/ Bu metot, Microsoft.AspNetCore.OpenApi paketi ile birlikte gelir ve Swagger UI i\u00e7in gerekli altyap\u0131y\u0131 sa\u011flar.\n\nvar app = builder.Build();\n\n\/\/ Configure the HTTP request pipeline.\nif (app.Environment.IsDevelopment())\n{\n \/\/ 2. Swagger UI'\u0131 geli\u015ftirme ortam\u0131nda etkinle\u015ftir\n app.UseSwagger(); \/\/ OpenAPI JSON belgesini sunar\n app.UseSwaggerUI(); \/\/ Swagger UI web aray\u00fcz\u00fcn\u00fc etkinle\u015ftirir\n}\n\napp.UseHttpsRedirection();\n\n\/\/ \u00d6rnek bir Minimal API endpoint'i\napp.MapGet(\"\/hello\", () => \"Merhaba .NET 9!\");\n\n\/\/ \u00d6rnek bir API endpoint'i (daha fazla detay ve etiketleme ile)\napp.MapGet(\"\/products\/{id}\", (int id) =>\n{\n \/\/ \u00dcr\u00fcn veritaban\u0131ndan \u00fcr\u00fcn \u00e7ekme sim\u00fclasyonu\n var product = new { Id = id, Name = $\"Product {id}\", Price = 19.99m };\n return Results.Ok(product);\n})\n.WithName(\"GetProductById\") \/\/ Endpoint'e \u00f6zel bir isim verir\n.WithOpenApi(operation => \/\/ OpenAPI tan\u0131m\u0131n\u0131 \u00f6zelle\u015ftir\n{\n operation.Summary = \"Belirli bir \u00fcr\u00fcn\u00fc ID ile getirir.\";\n operation.Description = \"\u00dcr\u00fcn katalo\u011fundan ID'ye g\u00f6re tek bir \u00fcr\u00fcn d\u00f6nd\u00fcr\u00fcr.\";\n return operation;\n})\n.WithTags(\"Products\"); \/\/ Endpoint'i bir grup alt\u0131nda etiketler (Swagger UI'da gruplama i\u00e7in)\n\napp.Run();\n <\/pre>\nAddEndpointsApiExplorer()<\/code> Minimal API'ler i\u00e7in endpoint ke\u015ffini etkinle\u015ftirirken, AddSwaggerGen()<\/code> OpenAPI \u015femas\u0131n\u0131n olu\u015fturulmas\u0131n\u0131 ve UseSwagger()<\/code> ile UseSwaggerUI()<\/code> ise bu \u015feman\u0131n sunulmas\u0131n\u0131 sa\u011flar. \u00d6zellikle WithOpenApi()<\/code> metodu, Minimal API endpoint'lerinize \u00f6zel OpenAPI detaylar\u0131 eklemenize olanak tan\u0131r. WithTags()<\/code> ise Swagger UI'da ilgili endpoint'leri gruplamak i\u00e7in kullan\u0131l\u0131r.\n <\/p>\n<\/li>\n
\n Projenizi \u00e7al\u0131\u015ft\u0131r\u0131n:<\/p>\n\ndotnet run\n <\/pre>\n
\n Uygulaman\u0131z \u00e7al\u0131\u015ft\u0131ktan sonra, genellikle https:\/\/localhost:7xxx\/swagger<\/code> adresinden Swagger UI'a eri\u015febilirsiniz. Taray\u0131c\u0131n\u0131zda a\u00e7t\u0131\u011f\u0131n\u0131zda, API endpoint'lerinizin listelendi\u011fi, etkile\u015fimli bir aray\u00fcz g\u00f6rmelisiniz. Minimal API'leriniz, GetProductById<\/code> gibi adland\u0131r\u0131lm\u0131\u015f endpoint'leriniz ve \u00f6zel a\u00e7\u0131klamalar\u0131n\u0131z burada g\u00f6r\u00fcnecektir.\n <\/li>\n<\/ol>\nVaka Analizi: B\u00fcy\u00fck Bir Kurumsal API'nin .NET 9'a Ge\u00e7i\u015fi ve Belgeleme S\u00fcreci<\/h2>\n
Senaryo: TechCorp'un E-ticaret API'si<\/h3>\n
Problemler ve Zorluklar<\/h3>\n
\n
\u00c7\u00f6z\u00fcm: .NET 9'a Ge\u00e7i\u015f ve Yerel OpenAPI Entegrasyonu<\/h3>\n
\n
Target Framework<\/code> olarak .NET 9<\/code> olarak ayarland\u0131.<\/li>\ncsproj<\/code> dosyalar\u0131ndan kald\u0131r\u0131ld\u0131. Program.cs<\/code> ve Startup.cs<\/code> (e\u011fer varsa) dosyalar\u0131ndaki AddSwaggerGen<\/code>, UseSwagger<\/code> ve UseSwaggerUI<\/code> \u00e7a\u011fr\u0131lar\u0131 ile ilgili t\u00fcm konfig\u00fcrasyon kodlar\u0131 temizlendi.<\/li>\nMicrosoft.AspNetCore.OpenApi<\/code> Entegrasyonu:<\/strong> Projeye Microsoft.AspNetCore.OpenApi<\/code> NuGet paketi eklendi.<\/li>\nProgram.cs<\/code> dosyas\u0131na a\u015fa\u011f\u0131daki yap\u0131land\u0131rma eklendi:\n\n\/\/ ... mevcut kodlar ...\nbuilder.Services.AddEndpointsApiExplorer();\nbuilder.Services.AddSwaggerGen(options =>\n{\n \/\/ API versiyonlama i\u00e7in bilgi ekleme\n options.SwaggerDoc(\"v1\", new Microsoft.OpenApi.Models.OpenApiInfo { Title = \"TechCorp API v1\", Version = \"v1\" });\n options.SwaggerDoc(\"v2\", new Microsoft.OpenApi.Models.OpenApiInfo { Title = \"TechCorp API v2\", Version = \"v2\" });\n\n \/\/ JWT kimlik do\u011frulamas\u0131 deste\u011fi ekleme\n options.AddSecurityDefinition(\"Bearer\", new Microsoft.OpenApi.Models.OpenApiSecurityScheme\n {\n In = Microsoft.OpenApi.Models.ParameterLocation.Header,\n Description = \"L\u00fctfen 'Bearer token' format\u0131nda token'\u0131n\u0131z\u0131 girin\",\n Name = \"Authorization\",\n Type = Microsoft.OpenApi.Models.SecuritySchemeType.ApiKey,\n Scheme = \"Bearer\"\n });\n\n options.AddSecurityRequirement(new Microsoft.OpenApi.Models.OpenApiSecurityRequirement\n {\n {\n new Microsoft.OpenApi.Models.OpenApiSecurityScheme\n {\n Reference = new Microsoft.OpenApi.Models.OpenApiReference\n {\n Type = Microsoft.OpenApi.Models.ReferenceType.SecurityScheme,\n Id = \"Bearer\"\n }\n },\n Array.EmptyWithTags<\/code>, WithSummary<\/code>, WithDescription<\/code> ve WithOpenApi<\/code> gibi metotlar kullan\u0131larak OpenAPI belgelemesi i\u00e7in zenginle\u015ftirildi. \u00d6rne\u011fin, \u00fcr\u00fcn listeleme endpoint'i \u015fu \u015fekilde g\u00fcncellendi:\n\napp.MapGet(\"\/api\/v1\/products\", () =>\n{\n \/\/ \u00dcr\u00fcnleri veritaban\u0131ndan \u00e7ekme mant\u0131\u011f\u0131\n var products = new List