API Dokümantasyonu Nasıl Hazırlanır? OpenAPI ve Swagger

Bir iş ortağınız sisteminize bağlanmak istediğinde ilk sorduğu şey genellikle “dokümanınız var mı?” olur. Kod ne kadar iyi yazılmış olursa olsun, nasıl kullanılacağı yazılı değilse karşı taraf deneme yanılmayla ilerler, sizin ekibiniz de sürekli soru cevaplar. API dokümantasyonu, bir API’nin hangi adreslerde hangi işlemleri yaptığını, ne beklediğini ve ne döndürdüğünü anlatan kullanım kılavuzudur. Bu yazıda iyi bir dokümanın içeriğini ve OpenAPI/Swagger ile nasıl standart hâle getirileceğini anlatacağım.

API dokümantasyonu neden bu kadar önemli?

Dokümantasyon çoğu zaman projenin sonuna bırakılan, “zaman kalırsa” yapılan bir iş gibi görülür. Oysa işletme açısından doğrudan maliyet etkisi vardır:

Entegrasyon süresi kısalır: Bayi veya yazılım firması, sizi aramadan bağlantıyı kurabilir.
Destek yükü azalır: Aynı soruları tekrar tekrar cevaplamak zorunda kalmazsınız.
Geliştirici bağımlılığı azalır: Projeyi yazan kişi ayrılsa bile yeni bir geliştirici yapıyı anlayabilir.
Hatalar erken yakalanır: Belgelemek, tasarımdaki tutarsızlıkları görünür kılar.

Bir API servisi sipariş ediyorsanız dokümanın teslim paketinde açıkça yer almasını isteyin. Bu konudaki diğer maddeleri API servisi yazdırmak: kapsam, güvenlik ve teslim yazısında topladım.

İyi bir dokümanda neler bulunur?

Kullanıcının ilk dakikada çalışan bir istek atabilmesi hedeflenmelidir. Bunun için şu bölümler gerekir:

Başlangıç rehberi: API’nin ne işe yaradığı, temel adres, erişim anahtarının nasıl alınacağı ve ilk örnek istek.
Kimlik doğrulama: Token veya anahtarın hangi başlıkta, hangi biçimde gönderileceği; süresi dolunca ne yapılacağı.
Uç nokta referansı: Her adres için metot, parametreler, zorunlu ve isteğe bağlı alanlar, örnek istek ve örnek cevap.
Hata kodları: Hangi durumda hangi kodun döndüğü ve hata cevabının yapısı.
Sınırlar: İstek limitleri, sayfa başına en fazla kayıt, dosya boyutu sınırları.
Sürüm notları: Hangi sürümde neyin değiştiği, hangi alanların kullanımdan kalkacağı.

OpenAPI ve Swagger nedir?

OpenAPI Specification, REST API’leri makinenin de okuyabileceği standart bir biçimde tanımlamaya yarayan açık bir şartnamedir. Eski adı Swagger Specification’dır; bugün “Swagger” adı daha çok bu şartnameyle çalışan araçlar için kullanılır. Örneğin Swagger UI, OpenAPI dosyasından tarayıcıda gezilebilen, denemeler yapılabilen etkileşimli bir doküman sayfası üretir.

OpenAPI dosyası YAML veya JSON biçiminde yazılır. Kısa bir örnek:

openapi: 3.0.3
info:
  title: Sipariş API
  version: 1.0.0
paths:
  /orders/{id}:
    get:
      summary: Tek bir siparişi getirir
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer }
      responses:
        '200': { description: Sipariş bulundu }
        '404': { description: Sipariş bulunamadı }

Bu tek dosyadan hem okunabilir bir doküman sayfası hem de farklı dillerde istemci kodu üretilebilir. Doküman ile kodun birbirinden kopmaması için bu dosyanın projeyle birlikte güncellenmesi şarttır.

Dokümantasyon hazırlamanın iki yolu

Yaklaşım	Nasıl işler?	Ne zaman uygun?
Önce tasarım (design-first)	OpenAPI dosyası önce yazılır, kod ona göre geliştirilir	Dış firmaların kullanacağı, baştan üzerinde anlaşılması gereken API’ler
Önce kod (code-first)	Koddaki açıklamalardan OpenAPI dosyası otomatik üretilir	Hızlı ilerleyen, iç kullanım ağırlıklı projeler

Önce tasarım yaklaşımında mobil ekip ile arka uç ekibi aynı dosya üzerinde anlaşıp paralel çalışabilir. Önce kod yaklaşımında ise dokümanın her zaman koda uygun olması kolaylaşır. Hangisi seçilirse seçilsin, dokümanın otomatik testlerle doğrulanması iyi bir pratiktir.

Dokümanı canlı tutmak

Eskimiş bir doküman, hiç olmamasından bile zararlı olabilir; çünkü kullanıcıyı yanlış yönlendirir. Dokümanı güncel tutmak için şunları öneriyorum:

OpenAPI dosyasını kaynak koduyla aynı depoda tutun ve her değişiklikte birlikte güncelleyin.
Örnek istekleri Postman gibi araçlarla koleksiyon hâline getirip paylaşın. Bu araçları API test araçları yazısında karşılaştırdım.
Değişiklikleri sürüm notlarıyla duyurun; kullanımdan kalkacak alanları önceden belirtin. Ayrıntılar için API versiyonlama yazısına göz atabilirsiniz.
Dış kullanıcılara gerçek veriye dokunmayan bir test ortamı sunun.

Sık görülen dokümantasyon hataları

İncelediğim dokümanlarda en çok karşılaştığım eksikler şunlar: örnek cevap yerine yalnızca alan listesi vermek, hata durumlarını hiç anlatmamak, tarih ve para birimi biçimlerini belirtmemek, zorunlu alanları işaretlememek. Bir başka yaygın hata da dokümanı yalnızca geliştiricinin anlayacağı kısaltmalarla yazmaktır. Doküman, API’yi ilk kez gören birinin okuyacağı düşünülerek hazırlanmalıdır.

Küçük bir senaryo bu farkı iyi gösterir. Bir bayi, sipariş oluşturma uç noktasına tarih alanını gün/ay/yıl biçiminde gönderiyor, sistem ise yıl-ay-gün bekliyor. Dokümanda biçim yazmıyorsa bayi yalnızca “400 Bad Request” cevabını görür ve sorunu bulmak için sizi arar. Biçimin ve örnek değerin yazılı olduğu bir API dokümantasyonu ise bu telefonu hiç çaldırmaz.

Bu işi nasıl birlikte yaparız?

Yeni bir API için ya da belgesiz kalmış mevcut bir API için dokümantasyon hazırlarken şu yolu izliyorum:

Mevcut durumu inceleme: API’nin kimler tarafından kullanıldığını ve en çok hangi noktalarda soru geldiğini konuşuruz.
Kapsam ve teklif: Belgelenecek uç noktaları, gerekiyorsa test ortamı ve örnek koleksiyonu içeren bir teklif hazırlarım.
OpenAPI dosyası ve doğrulama: Her uç noktayı gerçek isteklerle deneyerek belgeler, dokümanla kodun uyumlu olduğunu kontrol ederim.
Yayın ve teslim: Etkileşimli doküman sayfasını yayına alır, dosyanın nasıl güncelleneceğini ekibinize gösteririm.

Projenizi konuşmak için iletişim sayfasından bana ulaşabilirsiniz.

Sık sorulan sorular

Swagger ile OpenAPI aynı şey mi?

Tam olarak değil. OpenAPI, API tanımlama şartnamesinin adıdır; Swagger ise bu şartnamenin eski adı ve bugün onunla çalışan araç ailesinin adıdır.

Dokümantasyon herkese açık olmalı mı?

Zorunlu değildir. İç API’lerin dokümanı şifreyle korunan bir sayfada ya da yalnızca iş ortaklarına açık bir alanda tutulabilir.

WordPress REST API için de doküman hazırlanır mı?

WordPress’in yerleşik uç noktaları zaten belgelenmiştir. Ancak sizin eklediğiniz özel uç noktalar için ayrı doküman hazırlamak gerekir.

GraphQL API’ler nasıl belgelenir?

GraphQL’de şema, kendi kendini tanımlayan bir yapıdadır ve araçlar şemadan doküman üretebilir. Yine de örnek sorgular ve iş kuralları ayrıca açıklanmalıdır.

Sonuç

Doğru hazırlanmış bir API dokümantasyonu, entegrasyonları hızlandırır, destek yükünü azaltır ve yazılımınızı tek bir geliştiriciye bağımlı olmaktan kurtarır. OpenAPI ve Swagger gibi standartlar bu işi düzenli ve sürdürülebilir kılar. API’niz için dokümantasyon hazırlamak isterseniz bana yazabilirsiniz.

API Dokümantasyonu Nasıl Hazırlanır? (OpenAPI/Swagger)