OpenAPI, API dokümantasyonu ve test işlemlerini kolaylaştıran etkileşimli bir arayüz ve makine tarafından okunabilir belgeler sağlar. Bu kılavuz, SpringDoc kullanarak OpenAPI'yi Spring Boot uygulamanıza entegre etmenin yollarını gösterecektir.
OpenAPI, API dokümantasyonu ve test işlemlerini kolaylaştıran etkileşimli bir arayüz ve makine tarafından okunabilir belgeler sağlar. Bu kılavuz, SpringDoc kullanarak OpenAPI'yi Spring Boot uygulamanıza entegre etmenin yollarını gösterecektir.
Bu bölümde Neden OpenAPI Kullanmalıyız? konusunu netleştirip uygulamada kullanacağınız temel noktaları özetliyoruz.
📋 Şunlara sahip olduğunuzdan emin olun:
SpringDoc kullanarak OpenAPI'yi entegre etmek için aşağıdaki bağımlılığı projenize ekleyin:
<dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId> <version>2.1.0</version> </dependency>
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.1.0'
SpringDoc minimal konfigürasyon gerektirir. application.properties veya application.yml dosyası üzerinden dokümantasyonu özelleştirebilirsiniz.
Bu yapılandırmayı başlangıç noktası olarak alın, sonra ortamınıza göre değerleri uyarlayın.
springdoc.api-docs.path=/api-docs springdoc.swagger-ui.path=/swagger-ui.html
REST kontrollerinize ve modellerinize anotasyonlar ekleyerek OpenAPI dokümantasyonunu otomatik olarak oluşturabilirsiniz.
Uygulamayı aşağıdaki komutla çalıştırın:
./mvnw spring-boot:run
OpenAPI dokümantasyonuna erişmek için:
http://localhost:8080/api-docshttp://localhost:8080/swagger-ui.htmlSwagger UI arayüzüne erişerek oluşturulan API dokümantasyonunu test edebilirsiniz:
http://localhost:8080/swagger-ui.html adresine gidin.Artık OpenAPI için üretim odaklı bir Spring Boot temeliniz var. Sonraki adımda ayarları kendi domainine uyarlayıp test ve gözlemlenebilirlik katmanını ekleyerek gerçek trafik altında doğrulayın.
Controller Örneği
package com.example.openapi.controller; import com.example.openapi.model.User; import io.swagger.v3.oas.annotations.Operation; import io.swagger.v3.oas.annotations.media.Content; import io.swagger.v3.oas.annotations.responses.ApiResponse; import org.springframework.web.bind.annotation.*; import java.util.List; @RestController @RequestMapping("/users") public class UserController { @Operation(summary = "Tüm kullanıcıları getir", description = "Kullanıcı listesini alır") @ApiResponse(responseCode = "200", description = "Başarılı işlem", content = @Content(mediaType = "application/json")) @GetMapping public List<User> getAllUsers() { return List.of(new User(1L, "John Doe", "john@example.com")); } @Operation(summary = "Yeni bir kullanıcı oluştur", description = "Sisteme yeni bir kullanıcı ekler") @ApiResponse(responseCode = "201", description = "Kullanıcı başarıyla oluşturuldu", content = @Content(mediaType = "application/json")) @PostMapping public User createUser(@RequestBody User user) { return user; } }
User Model
package com.example.openapi.model; import lombok.AllArgsConstructor; import lombok.Data; import lombok.NoArgsConstructor; @Data @NoArgsConstructor @AllArgsConstructor public class User { private Long id; private String name; private String email; }
Controller Örneği
package com.example.openapi.controller import com.example.openapi.model.User import io.swagger.v3.oas.annotations.* import io.swagger.v3.oas.annotations.responses.* import io.swagger.v3.oas.annotations.media.* import org.springframework.web.bind.annotation.* @RestController @RequestMapping("/users") class UserController { @Operation(summary = "Tüm kullanıcıları getir", description = "Kullanıcı listesini alır") @ApiResponse(responseCode = "200", description = "Başarılı işlem", content = [Content(mediaType = "application/json")]) @GetMapping fun getAllUsers(): List<User> = listOf(User(1L, "John Doe", "john@example.com")) @Operation(summary = "Yeni bir kullanıcı oluştur", description = "Sisteme yeni bir kullanıcı ekler") @ApiResponse(responseCode = "201", description = "Kullanıcı başarıyla oluşturuldu", content = [Content(mediaType = "application/json")]) @PostMapping fun createUser(@RequestBody user: User): User = user }
User Model
package com.example.openapi.model data class User( val id: Long, val name: String, val email: String )