Java İle Swagger Kullanarak Apı Dokümantasyonu Nasıl Yapılır?

Gereksinimler ve Ön Hazırlık

Bu rehberi uygulamak için sisteminizde Java 17 veya üzeri bir sürümün yüklü olması gerekmektedir. Ayrıca, bir Spring Boot projesine ve temel düzeyde Maven veya Gradle bilgisine sahip olmanız yeterlidir. 2026 yılı standartları gereği, eski "Springfox" kütüphanesi yerine güncel ve aktif olarak desteklenen "SpringDoc OpenAPI" kütüphanesini kullanacağız.

• Java Development Kit (JDK) 17+
• Spring Boot 3.x sürümü
• Maven veya Gradle yapılandırma aracı
• Tercih edilen bir IDE (IntelliJ IDEA veya Eclipse)

Adım 1: SpringDoc OpenAPI Bağımlılıklarını Ekleme

Projenizin dokümantasyon özelliklerini kazanması için ilk adım, gerekli bağımlılıkları pom.xml dosyanıza eklemektir. Bu kütüphane, kodunuzdaki controller sınıflarını tarar ve otomatik olarak OpenAPI standartlarına uygun bir JSON dosyası üretir.

    org.springdoc
    springdoc-openapi-starter-webmvc-ui
    2.6.0

Bu bağımlılık, hem Swagger UI arayüzünü hem de API tanımlarını otomatik olarak yapılandırır. Ekledikten sonra projenizi "Maven Update" yaparak kütüphanenin indirilmesini sağlayın.

Adım 2: API Bilgilerini Yapılandırma

Dokümantasyonunuzun profesyonel görünmesi için API başlığı, versiyonu ve açıklama gibi bilgileri bir konfigürasyon sınıfında tanımlamanız önerilir. Bu, dokümantasyonun en üst kısmında yer alacak olan küresel bilgileri yönetmenizi sağlar.

@Configuration
public class OpenApiConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
            .info(new Info()
                .title("Kullanıcı Yönetim API")
                .version("1.0")
                .description("Kullanıcı kayıt ve listeleme işlemleri için oluşturulmuş API dokümantasyonu."));
    }
}

Bu kod bloğu, Swagger arayüzünde görünen başlıkları özelleştirir. @Configuration anotasyonu, Spring'in bu sınıfı uygulama başlangıcında işlemesini sağlar.

Adım 3: Controller Sınıflarını Anotasyonlarla Zenginleştirme

Swagger'ın kodunuzu daha iyi anlaması ve dokümantasyonda daha anlamlı açıklamalar sunması için Controller sınıflarınıza @Tag ve @Operation gibi anotasyonlar eklemelisiniz. Bu, API uç noktalarınızın ne işe yaradığını dokümantasyonda netleştirir.

@RestController
@RequestMapping("/api/users")
@Tag(name = "Kullanıcı İşlemleri", description = "Kullanıcı yönetimi API uç noktaları")
public class UserController {

    @GetMapping("/{id}")
    @Operation(summary = "Kullanıcı getir", description = "ID bilgisine göre kullanıcı detayını döner.")
    public ResponseEntity getUserById(@PathVariable Long id) {
        return ResponseEntity.ok(new User(id, "Ahmet Yılmaz"));
    }
}

Burada @Tag anotasyonu API'yi gruplamak için, @Operation ise her bir metodun ne işe yaradığını açıklamak için kullanılır.

Adım 4: Güvenli ve Standart API Yanıtları Oluşturma

API dokümantasyonunda hata kodlarını ve başarılı yanıtları göstermek, API'yi tüketen geliştiriciler için hayat kurtarıcıdır. @ApiResponse anotasyonu ile farklı HTTP durum kodlarını dokümante edebilirsiniz.

@ApiResponse(responseCode = "200", description = "Başarılı işlem")
@ApiResponse(responseCode = "404", description = "Kullanıcı bulunamadı")
@GetMapping("/{id}")
public ResponseEntity getUserById(@PathVariable Long id) {
    // İş mantığı burada yer alır
    return ResponseEntity.ok(new User(id, "Örnek Kullanıcı"));
}

Bu yapı, Swagger arayüzünde "Responses" başlığı altında otomatik bir tablo oluşturur ve geliştiricilerin API'nizden ne tür yanıtlar bekleyebileceğini görmesini sağlar.

Adım 5: Swagger UI Üzerinden Test Etme

Tüm yapılandırmalar tamamlandıktan sonra, uygulamanızı çalıştırın ve tarayıcınızda http://localhost:8080/swagger-ui.html adresine gidin. Burada, yazdığınız tüm uç noktaların listelendiğini ve "Try it out" butonu ile doğrudan API'nize istek atabildiğinizi göreceksiniz.

Kritik Güvenlik Uyarısı: Üretim (Production) ortamında Swagger UI'ı herkese açık bırakmak, API uç noktalarınızın keşfedilmesine ve güvenlik açıklarının (örneğin izinsiz veri erişimi) kolayca tespit edilmesine neden olabilir. Üretim ortamında application.properties dosyanızda springdoc.swagger-ui.enabled=false ayarını kullanarak dokümantasyonu devre dışı bırakmayı unutmayın.

Swagger Kullanım Yöntemlerinin Karşılaştırılması

Sıkça Sorulan Sorular

Swagger UI'a erişemiyorum, ne yapmalıyım?

Öncelikle application.properties dosyanızda springdoc.api-docs.path yolunun doğru ayarlandığından emin olun. Ayrıca, güvenlik yapılandırmanızda (Spring Security) /swagger-ui/** ve /v3/api-docs/** yollarının herkese açık (permitAll) olduğundan emin olun.

Swagger dokümantasyonunu nasıl gizleyebilirim?

Belirli bir Controller'ı dokümantasyonda göstermek istemiyorsanız, sınıfın üzerine @Hidden anotasyonunu eklemeniz yeterlidir.

API versiyonlamasını nasıl gösteririm?

SpringDoc, API versiyonlamasını otomatik olarak algılar. Eğer farklı versiyonlar (v1, v2) kullanıyorsanız, GroupedOpenApi bean'leri tanımlayarak her versiyon için ayrı bir dokümantasyon sayfası oluşturabilirsiniz.

JWT ile korunan API'lerde Swagger nasıl kullanılır?

Swagger arayüzünde "Authorize" butonu eklemek için bir SecurityScheme tanımlamanız ve bunu OpenAPI nesnesine eklemeniz gerekir. Böylece test isteklerinde JWT token'ınızı arayüz üzerinden gönderebilirsiniz.

Dokümantasyonun performans etkisi var mı?

SpringDoc, uygulama başlangıcında bir kez tarama yapar. Çalışma zamanında (runtime) ciddi bir performans etkisi yoktur, ancak çok büyük projelerde başlangıç süresini milisaniye bazında etkileyebilir.

İleri Düzey OpenAPI Özelleştirmeleri ve Schema Yönetimi

Standart anotasyonların ötesine geçerek, API dokümantasyonunuzu daha profesyonel ve okunabilir hale getirebilirsiniz. Özellikle veri modelleriniz karmaşıklaştığında, @Schema anotasyonu ile alanların kısıtlamalarını ve örnek değerlerini netleştirmek, API tüketicileri için büyük bir kolaylık sağlar.

Örnek Senaryo: Veri Modeli Kısıtlamaları

Aşağıdaki örnekte, bir kullanıcı kayıt nesnesinin Swagger üzerinde nasıl daha detaylı tanımlanabileceğini görebilirsiniz. example ve description parametreleri, dokümantasyonun kalitesini doğrudan artırır.

public class UserRequest {
    @Schema(description = "Kullanıcının benzersiz e-posta adresi", example = "test@example.com", required = true)
    private String email;

    @Schema(description = "Şifre en az 8 karakter olmalıdır", example = "GucluSifre123!", minLength = 8)
    private String password;
}

API Dokümantasyonunda Performans Optimizasyonu

Büyük ölçekli projelerde, yüzlerce endpoint'in olduğu bir API'de Swagger'ın çalışma zamanı maliyeti oluşabilir. Dokümantasyonun uygulama performansını etkilememesi için şu stratejileri izleyebilirsiniz:

• Lazy Loading: Dokümantasyonun sadece ihtiyaç duyulduğunda (örneğin /swagger-ui.html adresine gidildiğinde) yüklenmesini sağlayın.
• Gruplandırma (Grouping): API'lerinizi modüllere ayırarak dokümantasyonun tek bir devasa dosya yerine parçalı yüklenmesini sağlayın.
• Production Profili: Üretim ortamında dokümantasyonun tamamen devre dışı bırakılması veya sadece belirli IP adreslerine açılması önerilir.

Gruplandırma ile Dokümantasyon Yönetimi

Farklı iş birimlerini (örneğin: auth ve order) farklı dokümantasyon gruplarında toplamak, hem performans hem de yönetim açısından daha sağlıklıdır.

@Configuration
public class OpenApiConfig {
    @Bean
    public GroupedOpenApi authApi() {
        return GroupedOpenApi.builder()
                .group("auth-api")
                .pathsToMatch("/api/v1/auth/**")
                .build();
    }

    @Bean
    public GroupedOpenApi orderApi() {
        return GroupedOpenApi.builder()
                .group("order-api")
                .pathsToMatch("/api/v1/orders/**")
                .build();
    }
}

Deployment Sürecinde Swagger Entegrasyonu

CI/CD süreçlerinizde API dokümantasyonunun güncel kalması hayati önem taşır. Uygulamanız her ayağa kalktığında v3/api-docs endpoint'inden JSON çıktısını alıp, bunu bir statik siteye veya API Gateway'e otomatik olarak aktarabilirsiniz.

Özellikle mikroservis mimarilerinde, tüm servislerin dokümanlarını tek bir "API Portal" çatısı altında toplamak için Swagger Aggregator yöntemlerini araştırmanız, mimari standartlarınızı bir üst seviyeye taşıyacaktır.

Sonuç

Java ile Swagger kullanarak API dokümantasyonu yapmak, projenizin sürdürülebilirliği ve ekip içi iletişimi için en önemli adımlardan biridir. Bu rehberde, SpringDoc OpenAPI kütüphanesi ile nasıl otomatik ve interaktif bir dokümantasyon oluşturacağınızı öğrendiniz. Bir sonraki adım olarak, API'nize JWT tabanlı güvenlik katmanları ekleyerek dokümantasyonunuzu yetkilendirme süreçleriyle entegre etmeyi deneyebilirsiniz.

Sorumluluk Reddi: Bu rehberdeki kod örnekleri eğitim amaçlıdır. Uygulamanızda kullanmadan önce güvenlik açıklarını (SQL Injection, XSS vb.) kontrol etmeli ve giriş verilerini her zaman doğrulayarak (validation) işlemelisiniz. Üretim ortamında güvenlik yapılandırmalarınızı uzman bir güvenlik mimarı ile gözden geçirmeniz önerilir.