Satır İçi API Dökümantasyon’u Oluşturma Aracı

Herkese merhaba,
Sizlere RESTful bir web API geliştirilirken satır içine yazmış olduğunuz yorum satırlarından dokümantasyon oluşturma aracı olan ApiDoc’tan bahsedecğim. ApiDoc nodejs’i kullanarak sizlere kullanımı kolay ve anlaşılır bir html sayfası üretiyor. ApiDoc sayesinde, terminalden çalıştıracağınız tek satır komut ile API dökümantasyonunu elde edebilirsiniz. API geliştirirken en büyük sorunlardan bir tanesi, yapılan en küçük değişikliklerde hem yazılan kodların yorum satırlarının güncellenmesi hemde API dökümantasyonunda ki bilgilerin güncellenmesidir.

ApiDoc satıriçi yorum satırlarından istenilen bir taslağa göre çıktı üretiyor. İstersdeniz farklı tasarımda ki taslaklarıda kullanabilirsniz. Apidoc MIT özgür lisansı ile lisanslanmıştır, kullanımı için hiçbir ücret ödemezsiniz. Eğer apidoc’un gelişmesine katkıda bulunmak isterseniz kaynak kodlarına github adresinden ulaşabilirsiniz. https://github.com/apidoc/apidoc

Apidoc’un desteklediği programlama dillerinin listesi;

C#, Go, Dart, Java, JavaScript, PHP

/**
* This is a comment.
*/

Clojure

;;;;
;; This is a comment.
;;;;

CoffeeScript

###
This is a comment.
###

Erlang:

%{
This is a comment.
%}

Perl

#**
# This is a comment.
#*

Python

"""
This is a comment.
"""

Ruby

=begin
This is a comment.
=end

Apidoc nodejs ile yazılmıştır. Eğer bilgisayarınızda nodejs yüklü değil ise nodejs’in sayfasına göz atabilirsiniz. https://nodejs.org/ Ayrıca nodejs paket yöneticisi npm‘yide kurmanızı tavsiye ederim.

Apidoc kurulumuna gelecek olursak bilgisayarınızda şu komutu çalıştırmalısınız.

npm install apidoc -g

Kurulum başarılı bir şekilde tamamlandıktan sonra bir Laravel 4.2 projesinde apidoc’u nasıl kullanabileceğimize gelelim.

Projemiz aşşağıdaki gibi bir dizin yapısına sahip. Dizin yapısında en altta bulunan apidoc.json, _header.md ve _footer.md benim oluşturduğum dosyalar.

• laravel-application
  • app
  • bin
  • bootstrap
  • public
  • vendorlaravel-application
  • .env.php
  • artisan
  • apidoc.json
  • _footer.md
  • _header.md

apidoc.json Dosyası temel anlamda şu şekilde olabilir:

{
  "name": "Your App API Documentation Name",
  "version": "0.1.0",
  "description": "Your App API documentation descritption",
  "title": "Your App API Title",
  "url" : "http://your.app.url.com",
  "sampleUrl": "http://your.app.sample.url.com",
  "header": {
    "title": "Header Informations",
    "filename": "_header.md"
  },
  "footer": {
    "title": "Footer Informations",
    "filename": "_footer.md"
  },
  "order": [
    "@apiGroup Name1",
    "@apiGroup Name2",
    "@apiGroup Name3"
  ]
}

_footer.md ve _header.md dosyaları API hakkında bilgi vermek için kullanılabilir.

Bu işlemleri yaptıktan sonra aşşağıdaki komut ile app dizini altındaki yorum satırlarından public/apidoc dizinine dokümantasyon dosyaları oluşturulur.

apidoc -i app/ -o public/apidoc/

Apidoc’un kendi sitesinde çok daha detaylı örnekler olduğu için çok örnek göstermeyeçeğim.

Örnek bir yorum satırı:

/**
* @api {get} /reviews/:id Get Review Information
* @apiName GetReview
* @apiGroup Review
* @apiPermission none
* @apiVersion 0.2.0
*
* @apiParam {Number} id Review unique ID.
*
* @apiSuccess {String} sender Sender of the Review.
* @apiSuccess {String} receiver  Receiver of the Review.
* @apiSuccess {String} review  Review content of the Review.
*
* @apiSuccessExample Success-Response:
*     HTTP/1.1 200 OK
*     {
*       "sender": "Ahmet",
*       "receiver": "Mehmet"
*       "review": "Very good..."
*     }
*
* @apiError ModelNotFound The id of the Review was not found.
*
* @apiErrorExample Error-Response:
*     HTTP/1.1 404 ModelNotFound
*     {
*       "error": "ModelNotFound"
*     }
*/

Umarım faydalı bir yazı olmuştur.

Kolay gelsin…