Koray PEKER
Menu
  • Anasayfa
  • Kütüphane
  • Kategoriler
    • Java
    • Spring
    • Tasarım Şablonları
    • Git
    • Maven
    • ORM Çatıları
    • VCS
    • SDLC
    • DevOps
    • Algoritma
    • Eğitim
    • Diğer
  • Hakkımda
Menu

API Dokümantasyon Önemi ve Swagger

9 Şubat 20199 Şubat 2019 tarihinde yayımlandı

API’ler tüketilmek üzere(consume) tasarlandığından, tüketicinin API’nizi hızlı bir şekilde uygulayabilmesini ve anlaşılabilirliğini sağlamak önemlidir. Bu sebepledir ki api dokümantasyonu olmazsa olmazdır. Dokümantasyon hazırlamak da çoğumuza bir işkence gibi geliyor. Ayrıca hadi diyelim zar zor bir doküman oluşturdunuz güncelliğini korumak ve okunabilirliğini sağlamak da bir o kadar zor olabiliyor.

Bir tüketici dokümana baktığında “Bu servis ne iş yapar, tanımı nedir, içerisinde hangi operasyonları barındırır, bu operasyonların kullanım şekli nasıl olmalıdır, giriş çıkış parametreleri ne türdedir? ” gibi soruların cevaplarını alabiliyor olması gerekir. 

Swagger Nedir ? 

Swagger, Rest API’leri tasarlamanıza, oluşturmanıza, belgelendirmenize ve kullanmanıza yardımcı olabilecek OpenAPI şartnamesi etrafında oluşturulmuş bir dizi açık kaynaklı araçtır. Büyük Swagger araçları şunları içerir:

Swagger Editor – OpenAPI özelliklerini yazabileceğiniz tarayıcı tabanlı editör.
Swagger UI – OpenAPI özelliklerini etkileşimli API belgesi olarak sunar.
Swagger Codegen – bir OpenAPI spesifikasyonundan sunucu taslakları ve istemci kütüphaneleri oluşturur.

Swagger UI Kurulumu

Basit bir SpringBoot örneği üzerinden anlatacağım. Öncelikle pom.xml içerisine swagger-ui bağımlılıklarını ekliyoruz.

Daha sonra Swagger konfigürasyonu için aşağıdaki swagger konfigürasyon sınıfını oluşturuyoruz. 

Swagger ayarları artık hazır. Şimdi Personel işlemlerinin yapıldığı rest servislerimizi yazalım. 

Uygulamamızı ayağa kaldırıyoruz ve http://localhost:8080/swagger-ui.html adresinden rest apilerimizin belgelendiğini görebiliyoruz. 

Swagger sunduğu standart ve araçlarla API tasarım, geliştirme, dokümantasyon ve test aşamasında kolaylık sağlamaktadır. Siz de hemen kullanıp sonuçları görebilirsiniz. Yukarıda yapılan örneğimizi github adresinden çekebilirsiniz.

1 yorum yapıldı “API Dokümantasyon Önemi ve Swagger”

  1. hakan yıldırım dedi ki:
    12 Kasım 2020, 11:07

    Harika bir makale olmuş, elinize emeğinize sağlık, konu basite indirgenerek detaylı bir şekilde anlatılmış.. Teşekkür ederim

    Yanıtla

Bir yanıt yazın Yanıtı iptal et

E-posta adresiniz yayınlanmayacak. Gerekli alanlar * ile işaretlenmişlerdir

POPÜLER YAZILAR

  • Çalışma Masam
  • Bir Yazılımcının Sırt Çantası
  • Modern Veri Tabanları
  • CI (Continuous integration) ve CD (Continuous Delivery/Deployment)
  • NullPointerException’dan Kaçış
  • Java Branching Statements (Dallanma İfadeleri)
  • İlk işime veda :(
  • Yük Testi ve SoapUI
  • Project : Lombok
  • Enumeration nedir ?

Ara

Son Yazılar

  • Çalışma Masam
  • Apache Kafka
  • Postman API’ları Görselleştirme
  • MongoDB Cheat Sheet
  • Splunk 101 – Giriş
  • Yük Testi ve SoapUI
  • Modern Veri Tabanları
  • Senior Stajyer ?!
  • API Dokümantasyon Önemi ve Swagger
  • Kod Tekrarı(Code Duplication) ve DRY

TAKİP ET

©2025 Koray PEKER