class Swagger extends Post
@created_at(
"2025-01-14 14:05"
)
@tag(
"swagger"
)
***
Swagger, RESTful API’lerin tasarımını, oluşturulmasını, dokümante edilmesini ve tüm özelliklerinin test edilmesini kolaylaştıran bir araç takımıdır. Swagger, API geliştiricileri için bir standart sunar ve uygulama geliştirme sürecini düzenler. Swagger sayesinde API'ler hem geliştiricilere hem de kullanıcılara daha kolay anlaşılır bir hale gelir.
### **Swagger Dökümantasyonu Nedir?**
Swagger dökümantasyonu, bir API’nin tüm ayrıntılarını açıklayan ve kullanıcıların API’yi kolayca anlamasını ve kullanmasını sağlayan teknik bir belgedir. Bu dokümantasyon, API’deki tüm endpoint’leri, bunların metodlarını, parametrelerini, yanıt tiplerini ve hata mesajlarını detaylı bir şekilde açıklar.
### **Swagger’ın Temel Bileşenleri**
1. **OpenAPI Specification (OAS):**
Swagger’ın temelini oluşturan bir standart dildir. Bu dil, API’lerin yapısını tanımlar ve Swagger’ın JSON veya YAML formatında API dokümantasyonu oluşturmasına olanak tanır.
2. **Swagger UI:**
Kullanıcı dostu bir arayüz sunarak API’nin dokümantasyonunun interaktif bir şekilde sunulmasını sağlar. Swagger UI, API endpoint’lerinin test edilmesine de olanak tanır.
3. **Swagger Editor:**
API dokümantasyonu oluşturmak veya var olan dokümantasyonu düzenlemek için kullanılan bir aracıdır. Genellikle JSON veya YAML formatında yazılır.
4. **Swagger Codegen:**
Swagger dökümantasyonundan otomatik olarak istemci SDK’ları veya sunucu kodu oluşturmak için kullanılır.
### **Swagger Dökümantasyonu Nasıl Oluşturulur?**
Swagger dokümantasyonu oluşturmak için aşağıdaki adımları izleyebilirsiniz:
#### 1. **Swagger’ı Projeye Entegre Etme**
Swagger’ı projenize entegre etmek için kullandığınız programlama dili veya framework için uygun bir kütüphane ya da paket seçmelisiniz. Örneğin:
- **Laravel:** `DarkaOnLine/L5-Swagger`
- **Spring Boot:** `springdoc-openapi`
- **Express.js:** `swagger-ui-express` ve `swagger-jsdoc`
#### 2. **OpenAPI Specification Hazırlama**
Swagger dokümantasyonu JSON veya YAML formatında yazılır. Örnek bir YAML dosyası:
openapi: 3.0.0
info:
title: Örnek API
description: Çalışan bir API için Swagger dökümantasyonu.
version: 1.0.0
servers:
- url: https://api.ornek.com
paths:
/kullanicilar:
get:
summary: Tüm kullanıcıları listele
responses:
'200':
description: Başarılı istekswagger-codegen generate -i api.yaml -l javascript -o ./client-sdk