zircote/swagger-php, PHP ile geliştirilen RESTful API'ler için OpenAPI (Swagger) spesifikasyonuna uygun interaktif dokümantasyon üretmeyi sağlayan bir kütüphanedir. PHP 8'in attribute yapısını (tercihen) veya geleneksel PHPDoc annotasyonlarını kullanarak API uç noktalarınızı, parametrelerinizi, modellerinizi ve yanıtlarınızı tanımlamanıza olanak tanır. Böylece dokümantasyonu elle yazmak yerine kod üzerinden otomatik olarak güncel tutabilirsiniz. Bu yaklaşım, API geliştirme sürecinde dokümantasyonun senkronize kalmasını sağlar ve ekip içi iş birliğini kolaylaştırır.
Hangi ihtiyaçlarda değerlendirilebilir?
- PHP tabanlı REST API geliştiren yazılım ekipleri
- API dokümantasyonunu kodla birlikte sürdürmek isteyen kurumlar
- OpenAPI/Swagger tabanlı araçlarla entegre çalışmayı hedefleyen projeler
Yaygın kullanım alanları
Mevcut API'ye dokümantasyon ekleme
PHP ile yazılmış mevcut bir REST API'ye attribute veya annotasyon ekleyerek otomatik olarak Swagger dokümantasyonu oluşturabilirsiniz. Bu, API'nin kullanımını hem iç geliştiriciler hem de dış tüketiciler için kolaylaştırır.
API sürümlerini dokümante etme
API'nizde yaptığınız değişiklikleri dokümantasyona yansıtmak için kütüphane, kod üzerindeki tanımlamaları güncel tutmanıza yardımcı olur. Böylece sürüm geçişlerinde dokümantasyonun güncel kalması sağlanır.
OpenAPI tabanlı araçlarla entegrasyon
Üretilen OpenAPI spesifikasyonunu Swagger UI, Postman veya diğer API test araçlarıyla kullanarak API'nizi test edebilir ve tüketicilere interaktif bir arayüz sunabilirsiniz.
İncelenmesi gereken noktalar
- PHP sürümü ve attribute desteği: Attribute kullanımı için PHP 8.0 veya üzeri gerekir; PHPDoc annotasyonları daha eski sürümlerle uyumludur.
- Dokümantasyonun doğruluğu, kod üzerindeki tanımlamaların doğru ve eksiksiz yapılmasına bağlıdır; yanlış tanımlamalar yanıltıcı dokümantasyona yol açabilir.
- Kütüphane yalnızca dokümantasyon üretir; API'nin kendisini veya güvenlik katmanını yönetmez, bu nedenle API güvenliği ayrıca ele alınmalıdır.
WordPress.org
Kurulum ve geliştirme notları
Kurulum, Composer aracılığıyla yapılır. Resmi kurulum adımları sağlanmadığından genel Composer kullanımı önerilir.
Geliştirme sürecinde, API sınıflarına ve metodlarına attribute veya annotasyon ekleyerek OpenAPI tanımları oluşturulur. Kütüphane bu tanımları tarayarak JSON veya YAML formatında spesifikasyon üretir.
Hazır çözümün ötesinde
Özel geliştirme ne zaman değerlendirilebilir?
ZeplinGo olarak, PHP REST API projelerinizde swagger-php kütüphanesinin kullanımını değerlendirebilir, mevcut API altyapınıza uygun dokümantasyon stratejisi geliştirebiliriz. API'nizin ihtiyaçlarına göre özel çözümler tasarlamak için bizimle iletişime geçebilirsiniz.
Ücretsiz ön çalışma isteyin →Değerlendirme soruları
swagger-php ile PHPDoc annotasyonları hala destekleniyor mu?
Evet, kütüphane PHP attribute'ları tercih etmekle birlikte PHPDoc annotasyonlarını da desteklemektedir. Böylece daha eski PHP sürümleriyle çalışan projelerde de kullanılabilir.
swagger-php sadece dokümantasyon mu üretir?
Evet, swagger-php yalnızca OpenAPI spesifikasyonuna uygun dokümantasyon dosyaları üretir. API'nin çalışması, güvenliği veya test edilmesi gibi konularla ilgilenmez.
Bu paket ZeplinGo tarafından mı geliştiriliyor?
Hayır, zircote/swagger-php bağımsız bir açık kaynak pakettir. ZeplinGo bu paketi kullanarak size özel API dokümantasyon çözümleri geliştirebilir.
