Go Dilinde Swagger Dokümantasyonu Oluşturma

Go dilinde API geliştirirken, API'nizin nasıl kullanılacağına dair net bir dokümantasyon sağlamak önemlidir. Swagger (şimdi OpenAPI olarak da bilinir), API'lerinizi tanımlamanın, oluşturmanın, belgelemenin ve kullanmanın standart bir yolunu sunar. Bu yazıda, Go'da Swagger dokümantasyonu nasıl oluşturulur ve projenize nasıl entegre edilir adım adım anlatılacaktır.

Adım 1: Swag CLI Kurulumu

İlk adım olarak, swag CLI aracını kurarak başlayalım. Bu araç, Go projenizdeki yorumları okuyup otomatik olarak Swagger dokümantasyonu oluşturacak.

go get -u github.com/swaggo/swag/cmd/swag

Adım 2: API Yorum Satırlarını Yazma

Dokümantasyonunuzu otomatik olarak oluşturabilmek için, API handler fonksiyonlarınıza özel yorum satırları eklemeniz gerekiyor. Bu yorumlar, swag'ın dokümantasyonunuzu oluştururken kullanacağı meta verileri sağlar.

// GetUser godoc
// @Summary Kullanıcı detaylarını getirir
// @Description Kullanıcı detaylarını ID'ye göre getirir
// @Tags users
// @Accept  json
// @Produce  json
// @Param   id     path    int     true        "User ID"
// @Success 200 {object} User
// @Router /users/{id} [get]
func GetUser(w http.ResponseWriter, r *http.Request) {
    // Handler logic here
}

Adım 3: Swagger Dokümantasyonunu Oluşturma

Kodunuzdaki yorum satırlarına dayanarak Swagger dokümantasyonunu oluşturmak için projenizin kök dizininde swag init komutunu çalıştırın.

swag init -d ./application/cmd/server,./application/app/controllers/ilanlar,./application/app/controllers/ihaleler,./application/app/controllers/teklifler,./application/app/controllers/kullanicilar --parseDependency --parseInternal

Bu komut, docs dizini altında Swagger dokümantasyon dosyalarını (swagger.json, swagger.yaml ve docs.go) oluşturur.

Adım 4: Swagger UI Entegrasyonu

Oluşturulan Swagger dokümantasyonunu bir web arayüzünde görüntülemek için swaggo/http-swagger paketini projenize dahil edin. Bu paket, Swagger UI'ı Go web uygulamanıza entegre etmenizi sağlar.

import "github.com/swaggo/http-swagger" // http-swagger middleware

// Serve the swagger UI
http.Handle("/swagger", httpSwagger.WrapHandler)

Adım 5: Sunucuyu Başlatma ve Dokümantasyonu Görüntüleme

Sunucunuzu başlattıktan sonra, http://localhost:7706/swagger/index.html adresine giderek Swagger UI üzerinden API dokümantasyonunuzu görüntüleyebilirsiniz.