API lerinizi nasıl dökümante edersiniz ?

İyi dökümante edilmiş API ler geliştiricinin deneyimlemesini kolaylaştırmasının yanında API nin başarısı için de önemli bir gerekliliktir.İyi dökümantasyon artık düz yazı şeklinde değil  interaktif web tabanlı dökümantasyon şeklinde tasarlanması geliştirici için canlı API deneyimi sağlıyor ve bu şeklide geliştirici adaptasyonunu hızlandırıyor.Daha zengin API dökümantasyon üretme sürecini otomatikleştiren bir çok araç var.Bu araçlar ile zaman ve maliyeti azaltmasının yanında geliştirici adaptasyonunu da geliştirir.

API-Documentation-Header-

Sonuç olarak projelerimizde kullanmak için bu araçları öğrenmek faydalı olacaktır.Şimdi bunları listeleyelim ;

  • Swagger – RESTful web servislerini görselleştirilmesi, üretimi,tüketimi ve açıklaması için tam bir framework uygulamasıdır ve bunun için tanımlamalarıda belirtir.Asp.NET MVC projesinde örnek kullanım için yayınladığım demoya buradan bakabilirsiniz.
  • Mashery I/O Docs– Mashery I/O Docs API lerin kaynaklarını methodlarını ve parametrelerini bildirmek için JSON schema ları kullanır ve bu şemelar esnek ve genişletilebilir.
  • MuleSoft API Designer & Console – API tasarlayıcı ve API konsolu RAML tabanlı araçlardır.
  • Dexy – Genel amaçlı kullanılabiliecek bir dökümantasyon aracıdır.Herhangi bir dili destekler ve ayrıca Web API lerin dökümnatasyonu için de kullanılır.
  • MireDot – Dökümantasyon oluşturmak için JavaDocs, Jax-RS, Jackson ve benzeri java frameworklerinden veriyi birleştirir.
  • TurnAPI – Markdown standartlarını temel alan text-to-HTML dönüştürme aracıdır.
  • sphinxcontrib.httpdomain– Python and C/C++ için kullanılan genel amaçlı dökümantasyon aracıdır.RESTful API ler için de dökümantasyon oluşturur ve ayrıca  flask, bottle gibi frameworkleri de destekler.
  • Apigee Console To-Go – WADL (Web application Description Language) spesifikasyonlarını kullanan interaktif bir dökümantasyon konsoludur.
  • Apiary.io – API planları dökümante etmek ve çalıştırmak için Markdown syntax temelli özelleştirilmiş bir araçtır.
  • Enunciate – HTML dökümantasyon oluşturmayı Java build sürecine bağlayan açık kaynak kodlu dökümnatasyon oluşturma motorudur.
  • Doxygen – açıklamalı c++ kaynağından dökümantasyon oluşturmak için standart bir araç ama ek olarak C, Objective-C, C#, PHP, Java, Python gibi diğer popüler programlama dillerini de destekliyor.online ve offline dökümantasyon oluşturabilirsiniz.
  • Slate –  Static API dökümantasyonu oluşturmak için kullanılabilir.
  • ApiGen – PHP kaynak kodunuzdan api dökümantasyonu oluşturmak için

Şimdi de API dökümantasyonundaki birkaç güzel örneğe bakalım.

Bu araçları kullanarak gerçekten güzel arayüzlere sahip api dökümantasyonları oluşturabiliriz.Bir kaçını denemeyi unutmayın !

No Comments

Bir Cevap Yazın