Go API geli\u015ftiricileri i\u00e7in dok\u00fcmantasyon s\u00fcreci s\u0131k\u0131c\u0131 ve zaman al\u0131c\u0131 olabilir. Peki, API’n\u0131z\u0131n g\u00fcc\u00fcn\u00fc ortaya koyan, etkile\u015fimli ve her zaman g\u00fcncel bir dok\u00fcmantasyona sahip olmak istemez miydiniz? Swagger (\u015fimdiki ad\u0131yla OpenAPI), bu sorunu ortadan kald\u0131ran g\u00fc\u00e7l\u00fc bir ara\u00e7 setidir ve Go projelerinize entegre etmek, d\u00fc\u015f\u00fcnd\u00fc\u011f\u00fcn\u00fczden \u00e7ok daha basit ve verimli bir s\u00fcre\u00e7 sunar. Bu makale, Go tabanl\u0131 API’lar\u0131n\u0131za Swagger’\u0131 nas\u0131l ekleyece\u011finizi ad\u0131m ad\u0131m a\u00e7\u0131klayacakt\u0131r.<\/p>\n

Modern yaz\u0131l\u0131m geli\u015ftirme d\u00fcnyas\u0131nda, API’lar uygulamalar\u0131n omurgas\u0131n\u0131 olu\u015fturur. Bir mobil uygulama, web aray\u00fcz\u00fc veya ba\u015fka bir mikroservis olsun, hepsi temel olarak API’lar arac\u0131l\u0131\u011f\u0131yla etkile\u015fim kurar. Ancak bu kritik bile\u015fenin dok\u00fcmantasyonu genellikle g\u00f6z ard\u0131 edilir veya sonraya b\u0131rak\u0131l\u0131r. Manuel olarak yaz\u0131lan dok\u00fcmantasyonlar h\u0131zla g\u00fcncelli\u011fini yitirir, geli\u015ftirici ekibi b\u00fcy\u00fcd\u00fck\u00e7e veya API’da s\u0131k de\u011fi\u015fiklikler yap\u0131ld\u0131k\u00e7a bak\u0131m y\u00fck\u00fc dayan\u0131lmaz hale gelir. Bu durum, yeni geli\u015ftiricilerin projeye adaptasyonunu zorla\u015ft\u0131r\u0131r, frontend ekiplerinin API’\u0131 do\u011fru anlamas\u0131n\u0131 engeller ve entegrasyon s\u00fcre\u00e7lerinde gereksiz zaman kay\u0131plar\u0131na yol a\u00e7ar.<\/p>\n

G\u00fcncel olmayan bir API dok\u00fcmantasyonu, bir geli\u015ftiricinin kar\u015f\u0131la\u015fabilece\u011fi en b\u00fcy\u00fck engellerden biridir. \u00d6rne\u011fin, bir frontend geli\u015ftiricisi, API’dan belirli bir veri yap\u0131s\u0131 beklerken, backend’deki de\u011fi\u015fiklikler nedeniyle farkl\u0131 bir yan\u0131tla kar\u015f\u0131la\u015fabilir. Bu t\u00fcr uyumsuzluklar, hata ay\u0131klama s\u00fcrecini uzat\u0131r, yanl\u0131\u015f anla\u015f\u0131lmalara neden olur ve sonunda proje teslim s\u00fcrelerini olumsuz etkiler. Ayr\u0131ca, API’n\u0131z\u0131 d\u0131\u015f payda\u015flara veya \u00fc\u00e7\u00fcnc\u00fc taraf geli\u015ftiricilere a\u00e7t\u0131\u011f\u0131n\u0131zda, kapsaml\u0131 ve etkile\u015fimli bir dok\u00fcmantasyon, onlar\u0131n \u00fcr\u00fcn\u00fcn\u00fcz\u00fc benimsemesi ve kullanmas\u0131 i\u00e7in temel bir gerekliliktir. Geli\u015ftirici deneyimi (DX) a\u00e7\u0131s\u0131ndan bak\u0131ld\u0131\u011f\u0131nda, iyi belgelenmi\u015f bir API, geli\u015ftiricilerin \u00fcr\u00fcn\u00fcn\u00fczle daha h\u0131zl\u0131 ve keyifli bir \u015fekilde etkile\u015fim kurmas\u0131n\u0131 sa\u011flar. Otomatik dok\u00fcmantasyon ara\u00e7lar\u0131, bu sorunlar\u0131n \u00fcstesinden gelmek i\u00e7in tasarlanm\u0131\u015ft\u0131r. API kodunuzdaki yorumlardan veya tan\u0131mlamalardan yola \u00e7\u0131karak, s\u00fcrekli g\u00fcncel kalan, etkile\u015fimli bir dok\u00fcmantasyon sayfas\u0131 olu\u015ftururlar. Bu sayede, API her g\u00fcncellendi\u011finde dok\u00fcmantasyon da otomatik olarak tazelenir, insan hatas\u0131 riski minimize edilir ve ekipler aras\u0131ndaki ileti\u015fim ak\u0131\u015f\u0131 iyile\u015fir. Go ekosistemi, bu t\u00fcr ara\u00e7lar i\u00e7in olduk\u00e7a elveri\u015fli bir zemin sunar ve Swagger, bu alanda en pop\u00fcler ve etkili \u00e7\u00f6z\u00fcmlerden biridir.<\/p>\n

\n Uzman \u0130pucu: Manuel dok\u00fcmantasyon, teknik borcun erken bir g\u00f6stergesidir. Otomatik dok\u00fcmantasyona yat\u0131r\u0131m yapmak, uzun vadede geli\u015ftirme maliyetlerini ve hata oranlar\u0131n\u0131 \u00f6nemli \u00f6l\u00e7\u00fcde azalt\u0131r.\n<\/div>\n

Swagger (OpenAPI) Nedir ve Go Eko-sistemindeki Yeri Nas\u0131ld\u0131r?<\/h2>\n

Swagger, asl\u0131nda OpenAPI Spesifikasyonu’na dayanan bir dizi ara\u00e7tan olu\u015fan a\u00e7\u0131k kaynakl\u0131 bir projenin markas\u0131yd\u0131. G\u00fcn\u00fcm\u00fczde, “OpenAPI Spesifikasyonu” terimi, API’lar\u0131 makine taraf\u0131ndan okunabilir bir formatta (YAML veya JSON) tan\u0131mlamak i\u00e7in kullan\u0131lan standart dili ifade ederken; “Swagger” ise bu spesifikasyona dayal\u0131 ara\u00e7lar\u0131 (Swagger UI, Swagger Editor, Swagger Codegen gibi) kapsayan geni\u015f bir ekosistemi ifade eder. K\u0131sacas\u0131, OpenAPI, API’n\u0131z\u0131n ne yapt\u0131\u011f\u0131n\u0131 anlatan bir dilken, Swagger ara\u00e7lar\u0131 bu dili kullanarak API’n\u0131z\u0131 g\u00f6rselle\u015ftirmeye, test etmeye ve hatta istemci kodu olu\u015fturmaya yard\u0131mc\u0131 olur.<\/p>\n

OpenAPI Spesifikasyonu, RESTful API’lar\u0131n\u0131z\u0131n t\u00fcm detaylar\u0131n\u0131 (u\u00e7 noktalar, HTTP metotlar\u0131, parametreler, istek\/yan\u0131t formatlar\u0131, kimlik do\u011frulama mekanizmalar\u0131 ve hata yan\u0131tlar\u0131 gibi) tutarl\u0131 ve anla\u015f\u0131l\u0131r bir \u015fekilde tan\u0131mlaman\u0131z\u0131 sa\u011flar. Bu tan\u0131mlama dosyas\u0131, insan okunabilirli\u011finin yan\u0131 s\u0131ra, makineler taraf\u0131ndan da kolayca i\u015flenebilir. Bu \u00f6zellik, API ge\u00e7itleri, otomatik test ara\u00e7lar\u0131 ve istemci SDK olu\u015fturucular\u0131 gibi bir\u00e7ok otomasyon arac\u0131 i\u00e7in temel olu\u015fturur.<\/p>\n

Go ekosisteminde Swagger ve OpenAPI’nin yeri olduk\u00e7a sa\u011flamd\u0131r. Go, mikroservisler ve y\u00fcksek performansl\u0131 API’lar geli\u015ftirmek i\u00e7in pop\u00fcler bir dil oldu\u011fundan, bu API’lar\u0131n do\u011fru \u015fekilde belgelenmesi hayati \u00f6nem ta\u015f\u0131r. Go i\u00e7in \u00e7e\u015fitli Swagger entegrasyonlar\u0131 mevcuttur. Bunlardan en bilinenleri \u015funlard\u0131r:<\/p>\n

swag<\/code> (github.com\/swaggo\/swag):<\/strong> Go kaynak kodunuzdaki yorumlardan otomatik olarak OpenAPI spesifikasyonu (swagger.json<\/code>, swagger.yaml<\/code>) dosyalar\u0131n\u0131 olu\u015fturan bir komut sat\u0131r\u0131 arac\u0131d\u0131r. Bu ara\u00e7, genellikle Gin, Echo, Fiber gibi pop\u00fcler Go web framework’leriyle birlikte kullan\u0131lan {framework}-swagger<\/code> middleware’leri ile entegre olur. Kullan\u0131m\u0131 nispeten basittir ve Go geli\u015ftiricileri aras\u0131nda olduk\u00e7a yayg\u0131nd\u0131r.<\/li>\n

go-swagger<\/code> (github.com\/go-swagger\/go-swagger):<\/strong> Bu, daha kapsaml\u0131 bir \u00e7\u00f6z\u00fcmd\u00fcr. Mevcut bir OpenAPI spesifikasyonu dosyas\u0131ndan (swagger.json<\/code> veya swagger.yaml<\/code>) Go sunucu ve istemci kodu olu\u015fturabilir. Ayn\u0131 zamanda Go kodunuzdan da spesifikasyon olu\u015fturma yetene\u011fine sahiptir, ancak swag<\/code>‘e g\u00f6re daha fazla yap\u0131land\u0131rma ve \u00f6\u011frenme e\u011frisi gerektirebilir. B\u00fcy\u00fck projelerde, s\u00f6zle\u015fme odakl\u0131 (contract-first) geli\u015ftirme yakla\u015f\u0131m\u0131n\u0131 benimseyen ekipler i\u00e7in daha uygun olabilir.<\/li>\n<\/ul>\nBu makalede, swag<\/code> arac\u0131n\u0131 kullanarak Go API’m\u0131za nas\u0131l kolayca Swagger ekleyebilece\u011fimizi ad\u0131m ad\u0131m inceleyece\u011fiz. Bunun nedeni, ba\u015flang\u0131\u00e7 i\u00e7in daha az karma\u015f\u0131k olmas\u0131 ve mevcut bir Go projesine h\u0131zl\u0131ca entegre edilebilmesidir. Go’nun sade ve anla\u015f\u0131l\u0131r yap\u0131s\u0131yla birle\u015fen Swagger’\u0131n g\u00fcc\u00fc, API geli\u015ftirme s\u00fcrecinizi \u00e7ok daha verimli hale getirecektir. Bu sayede, geli\u015ftiricileriniz API’lar\u0131n\u0131z\u0131 daha h\u0131zl\u0131 anlay\u0131p kullanabilecek, potansiyel hatalar azalacak ve genel geli\u015ftirici deneyimi \u00f6nemli \u00f6l\u00e7\u00fcde artacakt\u0131r. Semantik zenginlik a\u00e7\u0131s\u0131ndan, “RESTful API”, “mikroservisler”, “kontrat odakl\u0131”, “istemci SDK”, “geli\u015ftirici deneyimi” gibi anahtar kelimeler, bu b\u00f6l\u00fcm\u00fcn amac\u0131n\u0131 peki\u015ftirmektedir.<\/p>\n Go Projenize Swagger’\u0131 Ad\u0131m Ad\u0131m Nas\u0131l Entegre Edersiniz?<\/h2>\nGo projenize Swagger eklemek, API’n\u0131z\u0131n dok\u00fcmantasyonunu otomatikle\u015ftirmenin ve geli\u015ftirici deneyimini iyile\u015ftirmenin en etkili yollar\u0131ndan biridir. Bu s\u00fcre\u00e7, \u00fc\u00e7 ana ad\u0131mdan olu\u015fur: gerekli paketleri kurmak, API kodunu Swagger yorumlar\u0131yla zenginle\u015ftirmek ve son olarak Swagger UI’\u0131 Go uygulaman\u0131za entegre etmek. A\u015fa\u011f\u0131daki ad\u0131mlar\u0131 takip ederek, bu entegrasyonu kolayca ger\u00e7ekle\u015ftirebilirsiniz. Bu \u00f6rnekte, pop\u00fcler Go web framework’lerinden Gin’i kullanaca\u011f\u0131z, ancak konseptler di\u011fer framework’ler (Echo, Fiber) i\u00e7in de benzerdir.<\/p>\n Gerekli Paketleri Kurulumu<\/h3>\n\u0130lk olarak, Swagger dok\u00fcmantasyonunu olu\u015fturmak ve sunmak i\u00e7in gerekli Go paketlerini projenize eklememiz gerekiyor. \u0130ki temel paket kuraca\u011f\u0131z:<\/p>\n \nswag<\/code> komut sat\u0131r\u0131 arac\u0131:<\/strong> Bu ara\u00e7, Go kodunuzdaki \u00f6zel yorumlardan OpenAPI spesifikasyon dosyalar\u0131n\u0131 (swagger.json<\/code> ve swagger.yaml<\/code>) \u00fcretmekten sorumludur.<\/li>\n gin-swagger<\/code> middleware’i:<\/strong> Bu middleware, \u00fcretilen Swagger dok\u00fcmantasyon dosyalar\u0131n\u0131 bir web aray\u00fcz\u00fc (Swagger UI) arac\u0131l\u0131\u011f\u0131yla sunman\u0131z\u0131 sa\u011flar.<\/li>\n<\/ol>\n\ngo get -u github.com\/swaggo\/swag\/cmd\/swag\ngo get -u github.com\/swaggo\/gin-swagger\ngo get -u github.com\/swaggo\/gin-swagger\/swaggerFiles # Swagger UI statik dosyalar\u0131 i\u00e7in\ngo get -u github.com\/gin-gonic\/gin # Web framework'\u00fc olarak Gin kullanacaksak\n<\/pre>\n<\/code><\/p>\n Bu komutlar, swag<\/code> arac\u0131n\u0131 $GOPATH\/bin<\/code> dizininize (veya benzeri bir PATH'e) kuracak ve gin-swagger<\/code> ile Gin ba\u011f\u0131ml\u0131l\u0131klar\u0131n\u0131 projenize ekleyecektir. Kurulumun ard\u0131ndan, swag<\/code> komutunu terminalinizde \u00e7al\u0131\u015ft\u0131rarak do\u011fru \u015fekilde kuruldu\u011fundan emin olabilirsiniz.<\/p>\n API Kodunuzu Swagger Yorumlar\u0131yla Zenginle\u015ftirme<\/h3>\n\u015eimdi s\u0131ra, API u\u00e7 noktalar\u0131n\u0131z\u0131 Swagger'\u0131n anlayaca\u011f\u0131 \u015fekilde yorumlarla donatmaya geldi. Bu yorumlar, swag<\/code> arac\u0131n\u0131n \u00e7al\u0131\u015ft\u0131r\u0131ld\u0131\u011f\u0131nda OpenAPI spesifikasyonu olu\u015fturmak i\u00e7in kullanaca\u011f\u0131 meta verilerdir. Ana fonksiyonunuzun (genellikle main.go<\/code>) en \u00fcst\u00fcne genel API bilgilerini tan\u0131mlayan yorumlar\u0131 ekleyerek ba\u015flay\u0131n. Ard\u0131ndan, her bir u\u00e7 nokta (route) i\u00e7in \u00f6zel yorum bloklar\u0131 olu\u015fturaca\u011f\u0131z.<\/p>\n \npackage main\n\nimport (\n\t\"net\/http\"\n\n\t\"github.com\/gin-gonic\/gin\"\n\n\t_ \"your-module-name\/docs\" \/\/ Olu\u015fturulan swagger dok\u00fcmanlar\u0131n\u0131n import edilmesi\n\tginSwagger \"github.com\/swaggo\/gin-swagger\"\n\t\"github.com\/swaggo\/gin-swagger\/swaggerFiles\"\n)\n\n\/\/ @title Go Swagger \u00d6rnek API\n\/\/ @version 1.0\n\/\/ @description Bu, Gin framework ile geli\u015ftirilmi\u015f bir \u00f6rnek API'dir.\n\/\/ @termsOfService http:\/\/swagger.io\/terms\/\n\n\/\/ @contact.name API Destek\n\/\/ @contact.url http:\/\/www.swagger.io\/support\n\/\/ @contact.email support@swagger.io\n\n\/\/ @license.name Apache 2.0\n\/\/ @license.url http:\/\/www.apache.org\/licenses\/LICENSE-2.0.html\n\n\/\/ @host localhost:8080\n\/\/ @BasePath \/api\/v1\n\/\/ @securityDefinitions.apikey ApiKeyAuth\n\/\/ @in header\n\/\/ @name Authorization\nfunc main() {\n\tr := gin.Default()\n\n\t\/\/ API Gruplamas\u0131\n\tv1 := r.Group(\"\/api\/v1\")\n\t{\n\t\tv1.GET(\"\/hello\", GetHello)\n\t\tv1.POST(\"\/users\", CreateUser)\n\t}\n\n\t\/\/ Swagger UI u\u00e7 noktas\u0131\n\tr.GET(\"\/swagger\/*any\", ginSwagger.WrapHandler(swaggerFiles.Handler))\n\n\tr.Run(\":8080\")\n}\n\n\/\/ User modelini tan\u0131mlayal\u0131m\ntype User struct {\n\tID int json:\"id\" example:\"1\"<\/code>\n\tName string json:\"name\" example:\"John Doe\"<\/code>\n\tEmail string json:\"email\" example:\"john.doe@example.com\"<\/code>\n}\n\n\/\/ @Summary Merhaba mesaj\u0131 d\u00f6nd\u00fcr\u00fcr\n\/\/ @Description Sunucudan basit bir \"Merhaba D\u00fcnya\" mesaj\u0131 al\u0131r.\n\/\/ @Tags Genel\n\/\/ @Accept json\n\/\/ @Produce plain\n\/\/ @Success 200 {string} string \"Merhaba D\u00fcnya\"\n\/\/ @Router \/hello [get]\nfunc GetHello(c *gin.Context) {\n\tc.String(http.StatusOK, \"Merhaba D\u00fcnya!\")\n}\n\n\/\/ @Summary Yeni bir kullan\u0131c\u0131 olu\u015fturur\n\/\/ @Description JSON payload ile yeni bir kullan\u0131c\u0131 kayd\u0131 olu\u015fturur.\n\/\/ @Tags Kullan\u0131c\u0131lar\n\/\/ @Accept json\n\/\/ @Produce json\n\/\/ @Param user body User true \"Olu\u015fturulacak kullan\u0131c\u0131 bilgileri\"\n\/\/ @Success 200 {object} User \"Ba\u015far\u0131yla olu\u015fturulan kullan\u0131c\u0131\"\n\/\/ @Failure 400 {string} string \"Ge\u00e7ersiz istek g\u00f6vdesi\"\n\/\/ @Router \/users [post]\nfunc CreateUser(c *gin.Context) {\n\tvar user User\n\tif err := c.BindJSON(&user); err != nil {\n\t\tc.JSON(http.StatusBadRequest, gin.H{\"error\": \"Ge\u00e7ersiz istek g\u00f6vdesi\"})\n\t\treturn\n\t}\n\t\/\/ Burada kullan\u0131c\u0131y\u0131 veritaban\u0131na kaydetme vb. i\u015flemler yap\u0131labilir\n\tuser.ID = 1 \/\/ \u00d6rnek ID atamas\u0131\n\tc.JSON(http.StatusOK, user)\n}\n<\/pre>\n<\/code><\/p>\n Yukar\u0131daki kod blo\u011funda, main.go<\/code> dosyas\u0131n\u0131n ba\u015f\u0131nda @title<\/code>, @version<\/code>, @host<\/code> gibi genel API bilgilerini tan\u0131mlad\u0131k. Ayr\u0131ca, her bir HTTP metodu (GetHello<\/code> ve CreateUser<\/code> fonksiyonlar\u0131) i\u00e7in @Summary<\/code>, @Description<\/code>, @Tags<\/code>, @Accept<\/code>, @Produce<\/code>, @Param<\/code> ve @Success<\/code> gibi detayl\u0131 yorumlar ekledik. \u00d6zellikle @Param<\/code> ve @Success<\/code> etiketleri, API'n\u0131z\u0131n bekledi\u011fi ve d\u00f6nd\u00fcrd\u00fc\u011f\u00fc veri modellerini User<\/code> struct'\u0131 gibi Go yap\u0131lar\u0131n\u0131 kullanarak tan\u0131mlaman\u0131za olanak tan\u0131r. _ \"your-module-name\/docs\"<\/code> sat\u0131r\u0131, daha sonra olu\u015fturulacak docs<\/code> klas\u00f6r\u00fcndeki dosyan\u0131n Go derleyicisi taraf\u0131ndan dikkate al\u0131nmas\u0131n\u0131 sa\u011flar. your-module-name<\/code> yerine projenizin ger\u00e7ek mod\u00fcl ad\u0131n\u0131 yazmal\u0131s\u0131n\u0131z (\u00f6rn: github.com\/kullaniciadi\/projeadi\/docs<\/code>).<\/p>\n Dok\u00fcmantasyon Dosyalar\u0131n\u0131 Olu\u015fturma<\/h3>\nYorumlar\u0131 kodunuza ekledikten sonra, swag<\/code> arac\u0131n\u0131 kullanarak OpenAPI spesifikasyonu dosyalar\u0131n\u0131 olu\u015fturma zaman\u0131 geldi. Terminalinizde, projenizin k\u00f6k dizininde a\u015fa\u011f\u0131daki komutu \u00e7al\u0131\u015ft\u0131r\u0131n:<\/p>\n \nswag init\n<\/pre>\n<\/code><\/p>\n Bu komut, projenizin k\u00f6k dizininde otomatik olarak bir docs\/<\/code> klas\u00f6r\u00fc olu\u015fturacak ve bu klas\u00f6r\u00fcn i\u00e7ine swagger.json<\/code>, swagger.yaml<\/code> ve docs.go<\/code> dosyalar\u0131n\u0131 yerle\u015ftirecektir. docs.go<\/code> dosyas\u0131, Swagger UI'\u0131n bu spesifikasyon dosyalar\u0131n\u0131 Go uygulamas\u0131 i\u00e7inde okumas\u0131 i\u00e7in gerekli olan kodu i\u00e7erir.<\/p>\n Swagger UI'\u0131 Go Uygulaman\u0131za Entegre Etme<\/h3>\nSon ad\u0131m, olu\u015fturulan dok\u00fcmantasyon dosyalar\u0131n\u0131 bir web taray\u0131c\u0131s\u0131 \u00fczerinden g\u00f6r\u00fcnt\u00fclenebilir hale getirmektir. Bu, gin-swagger<\/code> middleware'ini kullanarak yap\u0131l\u0131r. main.go<\/code> dosyan\u0131zdaki router tan\u0131mlamalar\u0131n\u0131z\u0131n aras\u0131na a\u015fa\u011f\u0131daki sat\u0131r\u0131 ekleyin:<\/p>\n \nr.GET(\"\/swagger\/*any\", ginSwagger.WrapHandler(swaggerFiles.Handler))\n<\/pre>\n<\/code><\/p>\n Bu sat\u0131r, \/swagger\/*any<\/code> yoluna gelen t\u00fcm istekleri ginSwagger.WrapHandler<\/code>'a y\u00f6nlendirir. Bu handler, swaggerFiles.Handler<\/code>'\u0131 kullanarak olu\u015fturulan swagger.json<\/code>\/swagger.yaml<\/code> dosyalar\u0131n\u0131 ve Swagger UI'\u0131n statik varl\u0131klar\u0131n\u0131 (HTML, CSS, JS) sunar. Art\u0131k uygulaman\u0131z\u0131 \u00e7al\u0131\u015ft\u0131r\u0131p (go run main.go<\/code>) bir web taray\u0131c\u0131s\u0131nda http:\/\/localhost:8080\/swagger\/index.html<\/code> adresine giderek etkile\u015fimli API dok\u00fcmantasyonunuzu g\u00f6r\u00fcnt\u00fcleyebilirsiniz. Bu entegrasyon sayesinde, API kodunuzda yapt\u0131\u011f\u0131n\u0131z her yorum de\u011fi\u015fikli\u011finden sonra swag init<\/code> komutunu \u00e7al\u0131\u015ft\u0131rarak dok\u00fcmantasyonunuzu an\u0131nda g\u00fcncelleyebilirsiniz. Bu, geli\u015ftirme s\u00fcrecini h\u0131zland\u0131r\u0131r ve dok\u00fcmantasyonun her zaman g\u00fcncel kalmas\u0131n\u0131 sa\u011flar.<\/p>\n Kapsaml\u0131 Bir Go API \u0130\u00e7in Swagger Kullan\u0131m Senaryolar\u0131 ve \u0130pu\u00e7lar\u0131<\/h2>\nSwagger'\u0131 Go API'n\u0131za entegre etmek sadece basit u\u00e7 noktalar\u0131 belgelemekle kalmaz, ayn\u0131 zamanda daha karma\u015f\u0131k senaryolar\u0131 da y\u00f6netmenize olanak tan\u0131r. Ger\u00e7ek d\u00fcnya uygulamalar\u0131nda s\u0131k\u00e7a kar\u015f\u0131la\u015f\u0131lan durumlar i\u00e7in Swagger yorumlar\u0131n\u0131 nas\u0131l kullanaca\u011f\u0131n\u0131z\u0131 bilmek, dok\u00fcmantasyonunuzun kapsam\u0131n\u0131 ve do\u011frulu\u011funu art\u0131racakt\u0131r. \u0130\u015fte baz\u0131 \u00f6nemli kullan\u0131m senaryolar\u0131 ve ipu\u00e7lar\u0131:<\/p>\n Kompleks \u0130stek\/Yan\u0131t G\u00f6vdeleri ve Modeller<\/h3>\nAPI'lar genellikle basit string'ler veya say\u0131lar yerine, i\u00e7 i\u00e7e ge\u00e7mi\u015f JSON objeleri gibi karma\u015f\u0131k veri yap\u0131lar\u0131yla \u00e7al\u0131\u015f\u0131r. Swagger, Go struct'lar\u0131n\u0131z\u0131 kullanarak bu karma\u015f\u0131k modelleri kolayca tan\u0131mlaman\u0131z\u0131 sa\u011flar. Yap\u0131land\u0131r\u0131lm\u0131\u015f modelleriniz i\u00e7in example<\/code> etiketleri kullanarak dok\u00fcmantasyonunuzda \u00f6rnek JSON g\u00f6sterimlerini sunabilirsiniz, bu da kullan\u0131c\u0131lar\u0131n beklenen veri format\u0131n\u0131 anlamas\u0131n\u0131 kolayla\u015ft\u0131r\u0131r.<\/p>\n \ntype Address struct {\n\tStreet string json:\"street\" example:\"123 Main St\"<\/code>\n\tCity string json:\"city\" example:\"Anytown\"<\/code>\n\tZipCode string json:\"zip_code\" example:\"12345\"<\/code>\n}\n\ntype UserProfile struct {\n\tID int json:\"id\" example:\"1\"<\/code>\n\tFirstName string json:\"first_name\" example:\"Jane\"<\/code>\n\tLastName string json:\"last_name\" example:\"Doe\"<\/code>\n\tAge int json:\"age\" example:\"30\"<\/code>\n\tAddresses []Address json:\"addresses\"<\/code> \/\/ \u0130\u00e7 i\u00e7e ge\u00e7mi\u015f model\n}\n\n\/\/ @Summary Kullan\u0131c\u0131 profilini g\u00fcncelle\n\/\/ @Description Mevcut bir kullan\u0131c\u0131n\u0131n profil bilgilerini g\u00fcnceller.\n\/\/ @Tags Kullan\u0131c\u0131lar\n\/\/ @Accept json\n\/\/ @Produce json\n\/\/ @Param id path int true \"Kullan\u0131c\u0131 ID\"\n\/\/ @Param profile body UserProfile true \"G\u00fcncellenecek kullan\u0131c\u0131 profil bilgileri\"\n\/\/ @Success 200 {object} UserProfile \"G\u00fcncellenmi\u015f kullan\u0131c\u0131 profili\"\n\/\/ @Failure 400 {object} map[string]string \"Ge\u00e7ersiz istek\"\n\/\/ @Failure 404 {object} map[string]string \"Kullan\u0131c\u0131 bulunamad\u0131\"\n\/\/ @Router \/users\/{id}\/profile [put]\nfunc UpdateUserProfile(c *gin.Context) {\n\t\/\/ ... (Uygulama mant\u0131\u011f\u0131)\n}\n<\/pre>\n<\/code><\/p>\n Yukar\u0131daki \u00f6rnekte, UserProfile<\/code> struct'\u0131 i\u00e7inde Address<\/code> struct'\u0131 kullan\u0131larak i\u00e7 i\u00e7e ge\u00e7mi\u015f bir veri yap\u0131s\u0131 tan\u0131mlanm\u0131\u015ft\u0131r. swag<\/code> arac\u0131, bu struct'lar\u0131 otomatik olarak OpenAPI \u015femalar\u0131na d\u00f6n\u00fc\u015ft\u00fcrecektir.<\/p>\n Path, Query ve Header Parametreleri<\/h3>\nAPI'lar genellikle URL yolunda (path), sorgu dizgisinde (query) veya istek ba\u015fl\u0131klar\u0131nda (headers) parametreler bekler. Bu parametreleri @Param<\/code> etiketiyle do\u011fru bir \u015fekilde belgelemek \u00e7ok \u00f6nemlidir. in<\/code> anahtar kelimesi ile parametrenin nerede beklendi\u011fini (path, query, header, body, formData) belirtmelisiniz.<\/p>\n \n\/\/ @Summary Belirli bir \u00fcr\u00fcn\u00fc getirir\n\/\/ @Description ID'ye g\u00f6re bir \u00fcr\u00fcn getirir\n\/\/ @Tags \u00dcr\u00fcnler\n\/\/ @Accept json\n\/\/ @Produce json\n\/\/ @Param product_id path int true \"\u00dcr\u00fcn\u00fcn benzersiz ID'si\" minlength(1)\n\/\/ @Param include_details query boolean false \"Detayl\u0131 bilgileri i\u00e7erip i\u00e7ermeyece\u011fi\" default(false)\n\/\/ @Param X-API-Key header string true \"API anahtar\u0131n\u0131z\"\n\/\/ @Success 200 {object} Product \"\u00dcr\u00fcn bilgileri\"\n\/\/ @Failure 404 {string} string \"\u00dcr\u00fcn bulunamad\u0131\"\n\/\/ @Router \/products\/{product_id} [get]\nfunc GetProductByID(c *gin.Context) {\n\t\/\/ ...\n}\n<\/pre>\n<\/code><\/p>\n Kimlik Do\u011frulama Mekanizmalar\u0131n\u0131n Belgelenmesi<\/h3>\nG\u00fcvenli API'lar i\u00e7in kimlik do\u011frulama mekanizmalar\u0131n\u0131 belgelemek zorunludur. Swagger, JWT (JSON Web Token), OAuth2, Basic Auth ve API Anahtarlar\u0131 gibi \u00e7e\u015fitli g\u00fcvenlik \u015femalar\u0131n\u0131 destekler. Genel API bilgilerini tan\u0131mlad\u0131\u011f\u0131n\u0131z yerde @securityDefinitions<\/code> etiketini kullanarak g\u00fcvenlik \u015femalar\u0131n\u0131 belirleyebilirsiniz. Ard\u0131ndan, belirli bir u\u00e7 noktan\u0131n bu g\u00fcvenlik tan\u0131m\u0131n\u0131 kulland\u0131\u011f\u0131n\u0131 @security<\/code> etiketiyle belirtebilirsiniz.<\/p>\n \n\/\/ @securityDefinitions.apikey ApiKeyAuth\n\/\/ @in header\n\/\/ @name Authorization\n\n\/\/ @Summary Yetkilendirilmi\u015f bir i\u015flemi ger\u00e7ekle\u015ftirir\n\/\/ @Description Bu u\u00e7 nokta, ge\u00e7erli bir API anahtar\u0131 gerektirir.\n\/\/ @Tags G\u00fcvenli \u0130\u015flemler\n\/\/ @Security ApiKeyAuth\n\/\/ @Accept json\n\/\/ @Produce json\n\/\/ @Success 200 {string} string \"\u0130\u015flem ba\u015far\u0131l\u0131\"\n\/\/ @Failure 401 {string} string \"Yetkilendirme gerekli\"\n\/\/ @Router \/secure-data [get]\nfunc GetSecureData(c *gin.Context) {\n\t\/\/ ...\n}\n<\/pre>\n<\/code><\/p>\n @in header<\/code> ve @name Authorization<\/code>, API anahtar\u0131n\u0131n HTTP iste\u011finin Authorization<\/code> ba\u015fl\u0131\u011f\u0131nda beklendi\u011fini belirtir. Bu, JWT tokenleri i\u00e7in de benzer \u015fekilde kullan\u0131l\u0131r (\u00f6rne\u011fin, Bearer your_token<\/code> format\u0131nda).<\/p>\n Hata Yan\u0131tlar\u0131n\u0131 Belgeleme<\/h3>\nBir API'nin nas\u0131l hata verdi\u011fini anlamak, ba\u015far\u0131l\u0131 yan\u0131tlar\u0131 anlamak kadar \u00f6nemlidir. Swagger, @Failure<\/code> etiketiyle \u00e7e\u015fitli hata durumlar\u0131n\u0131 ve d\u00f6nd\u00fcrd\u00fckleri yap\u0131lar\u0131 belgelemenizi sa\u011flar. Bu, istemci taraf\u0131 geli\u015ftiricilerin olas\u0131 sorunlara kar\u015f\u0131 daha sa\u011flam kod yazmas\u0131na yard\u0131mc\u0131 olur.<\/p>\n \n\/\/ @Failure 400 {object} ErrorResponse \"Ge\u00e7ersiz istek verisi\"\n\/\/ @Failure 401 {object} ErrorResponse \"Kimlik do\u011frulama hatas\u0131\"\n\/\/ @Failure 500 {object} ErrorResponse \"Sunucu i\u00e7 hatas\u0131\"\ntype ErrorResponse struct {\n\tCode int json:\"code\" example:\"400\"<\/code>\n\tMessage string json:\"message\" example:\"Ge\u00e7ersiz giri\u015f\"<\/code>\n}\n<\/pre>\n<\/code><\/p>\n Hata yan\u0131tlar\u0131 i\u00e7in de \u00f6zel bir Go struct tan\u0131mlay\u0131p bunu @Failure<\/code> etiketinde kullanmak, tutarl\u0131 ve a\u00e7\u0131klay\u0131c\u0131 hata mesajlar\u0131 sunman\u0131za yard\u0131mc\u0131 olur.<\/p>\n \n Uzman \u0130pucu: B\u00fcy\u00fck projelerde Swagger yorumlar\u0131n\u0131 mod\u00fcler hale getirmek i\u00e7in her Go dosyas\u0131na veya ilgili group'a \u00f6zel yorum bloklar\u0131 ekleyin. Bu, tek bir devasa main.go dosyas\u0131 yerine daha okunabilir ve y\u00f6netilebilir bir yap\u0131 sa\u011flar. Ayr\u0131ca, go generate<\/code> komutunu kullanarak swag init<\/code>'i otomatikle\u015ftirin.\n<\/div>\nGer\u00e7ek D\u00fcnya Projelerinde Swagger: Bir Vaka Analizi<\/h2>\nBir e-ticaret platformu geli\u015ftiren \"InnovateTech\" ad\u0131nda orta \u00f6l\u00e7ekli bir yaz\u0131l\u0131m \u015firketini ele alal\u0131m. \u015eirket, mikroservis mimarisi kullan\u0131yor ve \u00fcr\u00fcnler, kullan\u0131c\u0131lar, sipari\u015fler ve \u00f6demeler i\u00e7in ayr\u0131 Go tabanl\u0131 API'lar geli\u015ftiriyor. Ba\u015flang\u0131\u00e7ta, her ekip kendi API's\u0131n\u0131n dok\u00fcmantasyonunu manuel olarak Markdown dosyalar\u0131nda veya Confluence sayfalar\u0131nda tutuyordu. Bu durum, zamanla ciddi sorunlara yol a\u00e7t\u0131:<\/p>\n \nS\u00fcr\u00fcm Uyu\u015fmazl\u0131klar\u0131:<\/strong> Frontend ekibi, \u00fcr\u00fcn API's\u0131n\u0131n eski bir s\u00fcr\u00fcm\u00fcne g\u00f6re kod yazarken, backend ekibi API'da de\u011fi\u015fiklikler yapm\u0131\u015ft\u0131. Bu da frontend'de beklenmedik hatalara ve uzun hata ay\u0131klama s\u00fcre\u00e7lerine neden oldu.<\/li>\n Yeni Ekip \u00dcyelerinin Adaptasyonu:<\/strong> Yeni kat\u0131lan geli\u015ftiriciler, API'lar\u0131 anlamak ve projeye adapte olmak i\u00e7in haftalar harcad\u0131, \u00e7\u00fcnk\u00fc dok\u00fcmantasyon da\u011f\u0131n\u0131k, eksik ve g\u00fcncel de\u011fildi.<\/li>\n \u00dc\u00e7\u00fcnc\u00fc Taraf Entegrasyonlar\u0131:<\/strong> Harici bir \u00f6deme ge\u00e7idi entegre etmeye \u00e7al\u0131\u015f\u0131rken, API ekibi manuel dok\u00fcmantasyon haz\u0131rlamak zorunda kald\u0131, bu da zaman al\u0131c\u0131yd\u0131 ve yanl\u0131\u015f anla\u015f\u0131lmalara a\u00e7\u0131kt\u0131.<\/li>\n Test Otomasyonu Zorluklar\u0131:<\/strong> Otomatik API testleri yazmak, s\u00fcrekli de\u011fi\u015fen manuel dok\u00fcmantasyon nedeniyle imkans\u0131z hale geldi.<\/li>\n<\/ul>\nSwagger Entegrasyonu Sonras\u0131 Durum<\/h3>\nInnovateTech, bu sorunlar\u0131n \u00fcstesinden gelmek i\u00e7in t\u00fcm Go API'lar\u0131na swag<\/code> ve gin-swagger<\/code> (veya di\u011fer framework'ler i\u00e7in uygun middleware'leri) entegre etmeye karar verdi. Her mikroservis ekibi, kendi API'lar\u0131n\u0131 geli\u015ftirdik\u00e7e Swagger yorumlar\u0131n\u0131 kodlar\u0131na ekledi ve CI\/CD s\u00fcre\u00e7lerine swag init<\/code> komutunu entegre etti. B\u00f6ylece, her kod de\u011fi\u015fikli\u011fi ve deployment ile dok\u00fcmantasyon otomatik olarak g\u00fcncellenir hale geldi. Bu entegrasyonun sonu\u00e7lar\u0131 \u015fa\u015f\u0131rt\u0131c\u0131yd\u0131:<\/p>\n\n\n\n\n\n\n\n\n\n\n\u00d6zellik<\/th>\n Swagger \u00d6ncesi Durum<\/th>\n Swagger Sonras\u0131 Durum<\/th>\n<\/tr>\n<\/thead>\n Dok\u00fcmantasyon G\u00fcncelli\u011fi<\/strong><\/td>\n S\u0131k\u00e7a g\u00fcncel de\u011fil, manuel g\u00fcncelleme ile zaman kayb\u0131<\/td>\n API koduyla senkronize, otomatik g\u00fcncelleniyor<\/td>\n<\/tr>\n Geli\u015ftirici Adaptasyonu<\/strong><\/td>\n Yeni geli\u015ftiriciler i\u00e7in uzun ve zorlu \u00f6\u011frenme e\u011frisi<\/td>\n Etkile\u015fimli UI sayesinde h\u0131zl\u0131 adaptasyon, geli\u015ftirici verimlili\u011finde %30 art\u0131\u015f<\/td>\n<\/tr>\n Frontend-Backend Senkronizasyonu<\/strong><\/td>\n S\u0131k\u00e7a uyumsuzluklar, entegrasyon hatalar\u0131<\/td>\n A\u00e7\u0131k ve tutarl\u0131 API s\u00f6zle\u015fmeleri, hata oran\u0131 %20 azald\u0131<\/td>\n<\/tr>\n \u00dc\u00e7\u00fcnc\u00fc Taraf Entegrasyonlar\u0131<\/strong><\/td>\n Manuel dok\u00fcmantasyon, yanl\u0131\u015f anla\u015f\u0131lmalar<\/td>\n Kendili\u011finden hizmet veren, kolay entegrasyonlar, daha h\u0131zl\u0131 i\u015fbirli\u011fi<\/td>\n<\/tr>\n Test Otomasyonu<\/strong><\/td>\n Zorlu ve k\u0131r\u0131lgan testler<\/td>\n OpenAPI spesifikasyonundan otomatik test senaryolar\u0131 olu\u015fturma kolayl\u0131\u011f\u0131<\/td>\n<\/tr>\n API Ke\u015ffedilebilirli\u011fi<\/strong><\/td>\n API'lar\u0131 bulmak ve anlamak zor<\/td>\n Merkezi ve interaktif bir portal \u00fczerinden kolayca ke\u015ffedilebilir<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\nBu vaka analizi, Swagger'\u0131n sadece dok\u00fcmantasyon arac\u0131 olman\u0131n \u00f6tesinde, bir projenin genel geli\u015ftirme verimlili\u011fini, ekip i\u00e7i ileti\u015fimi ve d\u0131\u015f payda\u015flarla i\u015fbirli\u011fini nas\u0131l d\u00f6n\u00fc\u015ft\u00fcrebilece\u011fini a\u00e7\u0131k\u00e7a g\u00f6stermektedir. InnovateTech \u00f6rne\u011fi, \"API Gateway\" gibi kavramlarla da \u00f6rt\u00fc\u015ferek, farkl\u0131 mikroservislerin tek bir noktadan y\u00f6netilmesi ve belgelenmesinin \u00f6nemini vurgulamaktad\u0131r. Bu, geli\u015ftirme s\u00fcre\u00e7lerinde \"hata ay\u0131klama\" s\u00fcrelerini k\u0131salt\u0131rken, \"geli\u015ftirici deneyimini\" iyile\u015ftiren \u00f6nemli bir ad\u0131md\u0131r.<\/p>\n Geli\u015fmi\u015f Swagger \u00d6zellikleri ve Mobil Uyumluluk \u0130\u00e7in \u0130pu\u00e7lar\u0131<\/h2>\nSwagger'\u0131n temel entegrasyonu size harika bir ba\u015flang\u0131\u00e7 noktas\u0131 sunar, ancak arac\u0131n sundu\u011fu baz\u0131 geli\u015fmi\u015f \u00f6zellikler, dok\u00fcmantasyonunuzu daha da g\u00fc\u00e7lendirebilir ve farkl\u0131 kullan\u0131m senaryolar\u0131na uyarlaman\u0131za olanak tan\u0131r. Ayr\u0131ca, mobil cihazlar \u00fczerinden API dok\u00fcmantasyonuna eri\u015fimin \u00f6nemini de g\u00f6z ard\u0131 etmemek gerekir.<\/p>\n Swagger UI'\u0131 \u00d6zelle\u015ftirme<\/h3>\nVarsay\u0131lan Swagger UI temas\u0131 i\u015flevsel olsa da, \u015firketinizin markas\u0131na uygun hale getirmek veya belirli bilgileri \u00f6n plana \u00e7\u0131karmak isteyebilirsiniz. Swagger UI, CSS ve JavaScript enjeksiyonlar\u0131 yoluyla kapsaml\u0131 bir \u015fekilde \u00f6zelle\u015ftirilebilir. \u00d6rne\u011fin, \u00f6zel bir logo ekleyebilir, renk \u015femas\u0131n\u0131 de\u011fi\u015ftirebilir veya varsay\u0131lan olarak hangi sekmelerin a\u00e7\u0131k olaca\u011f\u0131n\u0131 belirleyebilirsiniz.<\/p>\n gin-swagger<\/code> gibi middleware'ler, genellikle Swagger UI yap\u0131land\u0131rma se\u00e7eneklerini do\u011frudan Go kodunuzdan ge\u00e7irmenize izin verir. Bu, ginSwagger.URL(\"http:\/\/localhost:8080\/swagger\/doc.json\")<\/code> gibi parametrelerle doc.json<\/code> dosyas\u0131n\u0131n nerede oldu\u011funu belirtmekten, daha karma\u015f\u0131k \u00f6zelle\u015ftirmelere kadar gidebilir. Tamamen \u00f6zel bir tema veya stil uygulamak i\u00e7in, swaggerFiles.Handler<\/code>'\u0131n sundu\u011fu dosyalar\u0131 \u00f6nbelle\u011fe al\u0131p de\u011fi\u015ftirebilir veya kendi statik dosya sunucunuzu kurarak \u00f6zel CSS ve JS dosyalar\u0131n\u0131 ekleyebilirsiniz. Bu genellikle, web\/swagger<\/code> gibi bir klas\u00f6re kendi index.html<\/code> dosyan\u0131z\u0131 kopyalay\u0131p d\u00fczenleyerek ve buradaki statik dosyalar\u0131 sunan bir handler kullanarak yap\u0131l\u0131r.<\/p>\n \n\/\/ \u00d6rnek: Swagger UI'a \u00f6zel bir CSS dosyas\u0131 ekleme (custom-styles.css dosyan\u0131z\u0131n web\/swagger i\u00e7inde oldu\u011funu varsayal\u0131m)\n\/\/ Bu, swaggerFiles.Handler<\/code> yerine kendi statik dosya sunucunuzu kullanman\u0131z gerekti\u011fi anlam\u0131na gelir.\n\/\/ Bu senaryo i\u00e7in Gin'in statik dosya sunucusunu kullanabiliriz:\n\/\/ r.Static(\"\/swagger\", \".\/web\/swagger\")\n\/\/ Ancak bu, Swagger UI'\u0131n dinamik olarak olu\u015fturdu\u011fu doc.json<\/code>'\u0131 almas\u0131n\u0131 zorla\u015ft\u0131rabilir.\n\/\/ Genellikle daha geli\u015fmi\u015f \u00f6zelle\u015ftirmeler i\u00e7in, ginSwagger.WrapHandler<\/code>'\u0131n sundu\u011fu opsiyonlara bakmak veya\n\/\/ Swagger UI'\u0131n kendi JS yap\u0131land\u0131rmas\u0131n\u0131 manip\u00fcle etmek daha do\u011frudur.\n\n\/\/ E\u011fer Swagger UI'\u0131 tamamen kontrol etmek isterseniz, Swagger UI dist dosyalar\u0131n\u0131 indirip\n\/\/ kendiniz servis edebilir ve i\u00e7indeki index.html'i \u00f6zelle\u015ftirebilirsiniz.\n\/\/ Ancak gin-swagger<\/code>'\u0131n sa\u011flad\u0131\u011f\u0131 kolayl\u0131\u011f\u0131 kaybetmi\u015f olursunuz.\n\/\/ En pratik yol, ginSwagger.WrapHandler<\/code>'\u0131n opsiyonlar\u0131n\u0131 kullanmakt\u0131r:\nr.GET(\"\/swagger\/*any\", ginSwagger.WrapHandler(swaggerFiles.Handler,\n ginSwagger.URL(\"http:\/\/localhost:8080\/swagger\/doc.json\"), \/\/ dok\u00fcman konumu\n ginSwagger.DefaultModelsExpandDepth(1), \/\/ modellerin ne kadar derin g\u00f6sterilece\u011fi\n ginSwagger.DocExpansion(\"none\"), \/\/ d\u00f6k\u00fcmanlar\u0131n varsay\u0131lan olarak nas\u0131l a\u00e7\u0131laca\u011f\u0131\n))\n<\/pre>\n<\/code><\/p>\n Burada g\u00f6sterilen ginSwagger.DefaultModelsExpandDepth<\/code> ve ginSwagger.DocExpansion<\/code> gibi se\u00e7enekler, UI'\u0131n varsay\u0131lan davran\u0131\u015f\u0131n\u0131 de\u011fi\u015ftirmenize olanak tan\u0131r. Daha derinlemesine \u00f6zelle\u015ftirme i\u00e7in, Swagger UI'\u0131n kendi JavaScript konfig\u00fcrasyonunu (ui.initOAuth<\/code>, ui.initReact<\/code> vb.) kullanman\u0131z gerekebilir, ki bu da genellikle swaggerFiles.Handler<\/code>'\u0131n yerine kendi \u00f6zel index.html<\/code> dosyan\u0131z\u0131 sunmay\u0131 gerektirir.<\/p>\n \u0130stemci SDK'lar\u0131 Olu\u015fturma<\/h3>\nOpenAPI spesifikasyonunun en g\u00fc\u00e7l\u00fc yanlar\u0131ndan biri, otomatik kod olu\u015fturma (code generation) yetene\u011fidir. Swagger Codegen gibi ara\u00e7lar, swagger.json<\/code> veya swagger.yaml<\/code> dosyan\u0131z\u0131 kullanarak Go, Python, JavaScript, Java gibi \u00e7e\u015fitli dillerde istemci SDK'lar\u0131 (API client libraries) veya sunucu taslaklar\u0131 olu\u015fturabilir. Bu, API'n\u0131z\u0131 t\u00fcketen di\u011fer ekiplerin veya d\u0131\u015f geli\u015ftiricilerin, manuel olarak API \u00e7a\u011fr\u0131lar\u0131 yazmak yerine \u00f6nceden olu\u015fturulmu\u015f tip-g\u00fcvenli istemci kodlar\u0131n\u0131 kullanmas\u0131n\u0131 sa\u011flar. Bu sayede, entegrasyon s\u00fcreci h\u0131zlan\u0131r, hatalar azal\u0131r ve \"geli\u015ftirici deneyimi\" \u00f6nemli \u00f6l\u00e7\u00fcde iyile\u015fir.<\/p>\n \n# \u00d6rnek: Swagger Codegen kullanarak JavaScript istemci olu\u015fturma (CLI ile)\n# \u0130lk olarak Swagger Codegen CLI arac\u0131n\u0131 kurman\u0131z gerekebilir\n# brew install swagger-codegen\nswagger-codegen generate -i http:\/\/localhost:8080\/swagger\/doc.json -l javascript -o .\/clients\/javascript-client\n\n# Go istemcisi olu\u015fturmak i\u00e7in (Java tabanl\u0131 Codegen jar dosyas\u0131 ile)\n# java -jar swagger-codegen-cli.jar generate -i http:\/\/localhost:8080\/swagger\/doc.json -l go -o .\/clients\/go-client\n<\/pre>\n<\/code><\/p>\n Bu komutlar, belirtilen API spesifikasyonundan otomatik olarak istemci kodu olu\u015fturur. Bu i\u015flem, mikroservisler aras\u0131nda ileti\u015fim kuran veya mobil uygulamalar geli\u015ftiren ekipler i\u00e7in paha bi\u00e7ilmez bir kolayl\u0131k sa\u011flar.<\/p>\n Mobil Uyumluluk ve Duyarl\u0131 Tasar\u0131m (Responsive Design)<\/h3>\nSwagger UI, kutudan \u00e7\u0131kt\u0131\u011f\u0131 haliyle duyarl\u0131d\u0131r (responsive). Yani, farkl\u0131 ekran boyutlar\u0131na (masa\u00fcst\u00fc, tablet, mobil) otomatik olarak uyum sa\u011flayacak \u015fekilde tasarlanm\u0131\u015ft\u0131r. Bu, geli\u015ftiricilerin veya API t\u00fcketicilerinin mobil cihazlar\u0131 \u00fczerinden API dok\u00fcmantasyonunu rahatl\u0131kla g\u00f6r\u00fcnt\u00fcleyebilece\u011fi anlam\u0131na gelir. Bu modern beklenti, herhangi bir web tabanl\u0131 aray\u00fcz i\u00e7in temel bir gerekliliktir. Swagger UI'\u0131n CSS yap\u0131s\u0131, bu duyarl\u0131l\u0131\u011f\u0131 sa\u011flamak \u00fczere in\u015fa edilmi\u015ftir.<\/p>\n E\u011fer Swagger UI'\u0131 a\u015f\u0131r\u0131 derecede \u00f6zelle\u015ftiriyor veya kendi API dok\u00fcmantasyon aray\u00fcz\u00fcn\u00fcz\u00fc ba\u015ftan sona in\u015fa ediyorsan\u0131z, mobil uyumlulu\u011fu sa\u011flamak i\u00e7in standart HTML ve CSS duyarl\u0131 tasar\u0131m prensiplerini uygulaman\u0131z gerekir. Bu, genellikle CSS Media Query'leri kullan\u0131larak yap\u0131l\u0131r.<\/p>\n \n\/* \u00d6rnek bir mobil uyumlu CSS medya sorgusu *\/\n\/* Bu kod do\u011frudan Go uygulaman\u0131zda yer almaz,\n ancak Swagger UI'\u0131 veya kendi dok\u00fcmantasyon aray\u00fcz\u00fcn\u00fcz\u00fc\n \u00f6zelle\u015ftirirken kullanabilece\u011finiz bir CSS \u00f6rne\u011fidir. *\/\n

\u00d6zellik<\/th>\n	Swagger \u00d6ncesi Durum<\/th>\n	Swagger Sonras\u0131 Durum<\/th>\n<\/tr>\n<\/thead>\n
Dok\u00fcmantasyon G\u00fcncelli\u011fi<\/strong><\/td>\n	S\u0131k\u00e7a g\u00fcncel de\u011fil, manuel g\u00fcncelleme ile zaman kayb\u0131<\/td>\n	API koduyla senkronize, otomatik g\u00fcncelleniyor<\/td>\n<\/tr>\n
Geli\u015ftirici Adaptasyonu<\/strong><\/td>\n	Yeni geli\u015ftiriciler i\u00e7in uzun ve zorlu \u00f6\u011frenme e\u011frisi<\/td>\n	Etkile\u015fimli UI sayesinde h\u0131zl\u0131 adaptasyon, geli\u015ftirici verimlili\u011finde %30 art\u0131\u015f<\/td>\n<\/tr>\n
Frontend-Backend Senkronizasyonu<\/strong><\/td>\n	S\u0131k\u00e7a uyumsuzluklar, entegrasyon hatalar\u0131<\/td>\n	A\u00e7\u0131k ve tutarl\u0131 API s\u00f6zle\u015fmeleri, hata oran\u0131 %20 azald\u0131<\/td>\n<\/tr>\n
\u00dc\u00e7\u00fcnc\u00fc Taraf Entegrasyonlar\u0131<\/strong><\/td>\n	Manuel dok\u00fcmantasyon, yanl\u0131\u015f anla\u015f\u0131lmalar<\/td>\n	Kendili\u011finden hizmet veren, kolay entegrasyonlar, daha h\u0131zl\u0131 i\u015fbirli\u011fi<\/td>\n<\/tr>\n
Test Otomasyonu<\/strong><\/td>\n	Zorlu ve k\u0131r\u0131lgan testler<\/td>\n	OpenAPI spesifikasyonundan otomatik test senaryolar\u0131 olu\u015fturma kolayl\u0131\u011f\u0131<\/td>\n<\/tr>\n
API Ke\u015ffedilebilirli\u011fi<\/strong><\/td>\n	API'lar\u0131 bulmak ve anlamak zor<\/td>\n	Merkezi ve interaktif bir portal \u00fczerinden kolayca ke\u015ffedilebilir<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n Bu vaka analizi, Swagger'\u0131n sadece dok\u00fcmantasyon arac\u0131 olman\u0131n \u00f6tesinde, bir projenin genel geli\u015ftirme verimlili\u011fini, ekip i\u00e7i ileti\u015fimi ve d\u0131\u015f payda\u015flarla i\u015fbirli\u011fini nas\u0131l d\u00f6n\u00fc\u015ft\u00fcrebilece\u011fini a\u00e7\u0131k\u00e7a g\u00f6stermektedir. InnovateTech \u00f6rne\u011fi, \"API Gateway\" gibi kavramlarla da \u00f6rt\u00fc\u015ferek, farkl\u0131 mikroservislerin tek bir noktadan y\u00f6netilmesi ve belgelenmesinin \u00f6nemini vurgulamaktad\u0131r. Bu, geli\u015ftirme s\u00fcre\u00e7lerinde \"hata ay\u0131klama\" s\u00fcrelerini k\u0131salt\u0131rken, \"geli\u015ftirici deneyimini\" iyile\u015ftiren \u00f6nemli bir ad\u0131md\u0131r.<\/p>\n Geli\u015fmi\u015f Swagger \u00d6zellikleri ve Mobil Uyumluluk \u0130\u00e7in \u0130pu\u00e7lar\u0131<\/h2>\n Swagger'\u0131n temel entegrasyonu size harika bir ba\u015flang\u0131\u00e7 noktas\u0131 sunar, ancak arac\u0131n sundu\u011fu baz\u0131 geli\u015fmi\u015f \u00f6zellikler, dok\u00fcmantasyonunuzu daha da g\u00fc\u00e7lendirebilir ve farkl\u0131 kullan\u0131m senaryolar\u0131na uyarlaman\u0131za olanak tan\u0131r. Ayr\u0131ca, mobil cihazlar \u00fczerinden API dok\u00fcmantasyonuna eri\u015fimin \u00f6nemini de g\u00f6z ard\u0131 etmemek gerekir.<\/p>\n Swagger UI'\u0131 \u00d6zelle\u015ftirme<\/h3>\n Varsay\u0131lan Swagger UI temas\u0131 i\u015flevsel olsa da, \u015firketinizin markas\u0131na uygun hale getirmek veya belirli bilgileri \u00f6n plana \u00e7\u0131karmak isteyebilirsiniz. Swagger UI, CSS ve JavaScript enjeksiyonlar\u0131 yoluyla kapsaml\u0131 bir \u015fekilde \u00f6zelle\u015ftirilebilir. \u00d6rne\u011fin, \u00f6zel bir logo ekleyebilir, renk \u015femas\u0131n\u0131 de\u011fi\u015ftirebilir veya varsay\u0131lan olarak hangi sekmelerin a\u00e7\u0131k olaca\u011f\u0131n\u0131 belirleyebilirsiniz.<\/p>\n gin-swagger<\/code> gibi middleware'ler, genellikle Swagger UI yap\u0131land\u0131rma se\u00e7eneklerini do\u011frudan Go kodunuzdan ge\u00e7irmenize izin verir. Bu, ginSwagger.URL(\"http:\/\/localhost:8080\/swagger\/doc.json\")<\/code> gibi parametrelerle doc.json<\/code> dosyas\u0131n\u0131n nerede oldu\u011funu belirtmekten, daha karma\u015f\u0131k \u00f6zelle\u015ftirmelere kadar gidebilir. Tamamen \u00f6zel bir tema veya stil uygulamak i\u00e7in, swaggerFiles.Handler<\/code>'\u0131n sundu\u011fu dosyalar\u0131 \u00f6nbelle\u011fe al\u0131p de\u011fi\u015ftirebilir veya kendi statik dosya sunucunuzu kurarak \u00f6zel CSS ve JS dosyalar\u0131n\u0131 ekleyebilirsiniz. Bu genellikle, web\/swagger<\/code> gibi bir klas\u00f6re kendi index.html<\/code> dosyan\u0131z\u0131 kopyalay\u0131p d\u00fczenleyerek ve buradaki statik dosyalar\u0131 sunan bir handler kullanarak yap\u0131l\u0131r.<\/p>\n \n\/\/ \u00d6rnek: Swagger UI'a \u00f6zel bir CSS dosyas\u0131 ekleme (custom-styles.css dosyan\u0131z\u0131n web\/swagger i\u00e7inde oldu\u011funu varsayal\u0131m)\n\/\/ Bu, swaggerFiles.Handler<\/code> yerine kendi statik dosya sunucunuzu kullanman\u0131z gerekti\u011fi anlam\u0131na gelir.\n\/\/ Bu senaryo i\u00e7in Gin'in statik dosya sunucusunu kullanabiliriz:\n\/\/ r.Static(\"\/swagger\", \".\/web\/swagger\")\n\/\/ Ancak bu, Swagger UI'\u0131n dinamik olarak olu\u015fturdu\u011fu doc.json<\/code>'\u0131 almas\u0131n\u0131 zorla\u015ft\u0131rabilir.\n\/\/ Genellikle daha geli\u015fmi\u015f \u00f6zelle\u015ftirmeler i\u00e7in, ginSwagger.WrapHandler<\/code>'\u0131n sundu\u011fu opsiyonlara bakmak veya\n\/\/ Swagger UI'\u0131n kendi JS yap\u0131land\u0131rmas\u0131n\u0131 manip\u00fcle etmek daha do\u011frudur.\n\n\/\/ E\u011fer Swagger UI'\u0131 tamamen kontrol etmek isterseniz, Swagger UI dist dosyalar\u0131n\u0131 indirip\n\/\/ kendiniz servis edebilir ve i\u00e7indeki index.html'i \u00f6zelle\u015ftirebilirsiniz.\n\/\/ Ancak gin-swagger<\/code>'\u0131n sa\u011flad\u0131\u011f\u0131 kolayl\u0131\u011f\u0131 kaybetmi\u015f olursunuz.\n\/\/ En pratik yol, ginSwagger.WrapHandler<\/code>'\u0131n opsiyonlar\u0131n\u0131 kullanmakt\u0131r:\nr.GET(\"\/swagger\/any\", ginSwagger.WrapHandler(swaggerFiles.Handler,\n ginSwagger.URL(\"http:\/\/localhost:8080\/swagger\/doc.json\"), \/\/ dok\u00fcman konumu\n ginSwagger.DefaultModelsExpandDepth(1), \/\/ modellerin ne kadar derin g\u00f6sterilece\u011fi\n ginSwagger.DocExpansion(\"none\"), \/\/ d\u00f6k\u00fcmanlar\u0131n varsay\u0131lan olarak nas\u0131l a\u00e7\u0131laca\u011f\u0131\n))\n<\/pre>\n<\/code><\/p>\n Burada g\u00f6sterilen ginSwagger.DefaultModelsExpandDepth<\/code> ve ginSwagger.DocExpansion<\/code> gibi se\u00e7enekler, UI'\u0131n varsay\u0131lan davran\u0131\u015f\u0131n\u0131 de\u011fi\u015ftirmenize olanak tan\u0131r. Daha derinlemesine \u00f6zelle\u015ftirme i\u00e7in, Swagger UI'\u0131n kendi JavaScript konfig\u00fcrasyonunu (ui.initOAuth<\/code>, ui.initReact<\/code> vb.) kullanman\u0131z gerekebilir, ki bu da genellikle swaggerFiles.Handler<\/code>'\u0131n yerine kendi \u00f6zel index.html<\/code> dosyan\u0131z\u0131 sunmay\u0131 gerektirir.<\/p>\n \u0130stemci SDK'lar\u0131 Olu\u015fturma<\/h3>\nOpenAPI spesifikasyonunun en g\u00fc\u00e7l\u00fc yanlar\u0131ndan biri, otomatik kod olu\u015fturma (code generation) yetene\u011fidir. Swagger Codegen gibi ara\u00e7lar, swagger.json<\/code> veya swagger.yaml<\/code> dosyan\u0131z\u0131 kullanarak Go, Python, JavaScript, Java gibi \u00e7e\u015fitli dillerde istemci SDK'lar\u0131 (API client libraries) veya sunucu taslaklar\u0131 olu\u015fturabilir. Bu, API'n\u0131z\u0131 t\u00fcketen di\u011fer ekiplerin veya d\u0131\u015f geli\u015ftiricilerin, manuel olarak API \u00e7a\u011fr\u0131lar\u0131 yazmak yerine \u00f6nceden olu\u015fturulmu\u015f tip-g\u00fcvenli istemci kodlar\u0131n\u0131 kullanmas\u0131n\u0131 sa\u011flar. Bu sayede, entegrasyon s\u00fcreci h\u0131zlan\u0131r, hatalar azal\u0131r ve \"geli\u015ftirici deneyimi\" \u00f6nemli \u00f6l\u00e7\u00fcde iyile\u015fir.<\/p>\n \n# \u00d6rnek: Swagger Codegen kullanarak JavaScript istemci olu\u015fturma (CLI ile)\n# \u0130lk olarak Swagger Codegen CLI arac\u0131n\u0131 kurman\u0131z gerekebilir\n# brew install swagger-codegen\nswagger-codegen generate -i http:\/\/localhost:8080\/swagger\/doc.json -l javascript -o .\/clients\/javascript-client\n\n# Go istemcisi olu\u015fturmak i\u00e7in (Java tabanl\u0131 Codegen jar dosyas\u0131 ile)\n# java -jar swagger-codegen-cli.jar generate -i http:\/\/localhost:8080\/swagger\/doc.json -l go -o .\/clients\/go-client\n<\/pre>\n<\/code><\/p>\n Bu komutlar, belirtilen API spesifikasyonundan otomatik olarak istemci kodu olu\u015fturur. Bu i\u015flem, mikroservisler aras\u0131nda ileti\u015fim kuran veya mobil uygulamalar geli\u015ftiren ekipler i\u00e7in paha bi\u00e7ilmez bir kolayl\u0131k sa\u011flar.<\/p>\n Mobil Uyumluluk ve Duyarl\u0131 Tasar\u0131m (Responsive Design)<\/h3>\nSwagger UI, kutudan \u00e7\u0131kt\u0131\u011f\u0131 haliyle duyarl\u0131d\u0131r (responsive). Yani, farkl\u0131 ekran boyutlar\u0131na (masa\u00fcst\u00fc, tablet, mobil) otomatik olarak uyum sa\u011flayacak \u015fekilde tasarlanm\u0131\u015ft\u0131r. Bu, geli\u015ftiricilerin veya API t\u00fcketicilerinin mobil cihazlar\u0131 \u00fczerinden API dok\u00fcmantasyonunu rahatl\u0131kla g\u00f6r\u00fcnt\u00fcleyebilece\u011fi anlam\u0131na gelir. Bu modern beklenti, herhangi bir web tabanl\u0131 aray\u00fcz i\u00e7in temel bir gerekliliktir. Swagger UI'\u0131n CSS yap\u0131s\u0131, bu duyarl\u0131l\u0131\u011f\u0131 sa\u011flamak \u00fczere in\u015fa edilmi\u015ftir.<\/p>\n E\u011fer Swagger UI'\u0131 a\u015f\u0131r\u0131 derecede \u00f6zelle\u015ftiriyor veya kendi API dok\u00fcmantasyon aray\u00fcz\u00fcn\u00fcz\u00fc ba\u015ftan sona in\u015fa ediyorsan\u0131z, mobil uyumlulu\u011fu sa\u011flamak i\u00e7in standart HTML ve CSS duyarl\u0131 tasar\u0131m prensiplerini uygulaman\u0131z gerekir. Bu, genellikle CSS Media Query'leri kullan\u0131larak yap\u0131l\u0131r.<\/p>\n \n\/ \u00d6rnek bir mobil uyumlu CSS medya sorgusu \/\n\/ Bu kod do\u011frudan Go uygulaman\u0131zda yer almaz,\n ancak Swagger UI'\u0131 veya kendi dok\u00fcmantasyon aray\u00fcz\u00fcn\u00fcz\u00fc\n \u00f6zelle\u015ftirirken kullanabilece\u011finiz bir CSS \u00f6rne\u011fidir. *\/\n