Laravel'de Swagger ile Rest Api dokümantasyonu hazırlama

Merhabalar,


Bu yazıda Laravel'de Swagger ile Rest Api dokümantasyonu hazırlamayı temel özellikleriyle anlatacağım. Örnek projeyi Github üzerinden paylaştım. İndirip inceleyebilirsiniz.


Örnek Proje Linki


Elbette her şeyden önce işe boş bir Laravel projesi oluşturarak başlıyoruz:

composer create-project --prefer-dist laravel/laravel swagger-sample


Sonrasında Swagger için gerekli paketi kuruyoruz:

composer require "darkaonline/l5-swagger:5.8.*"


Kurmuş olduğumuz paketi projeye entegre etmek için şu komutu çalıştırıyoruz:

php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"


Swagger'da kullanılan tanımlamaların Laravel (Php) tarafından algılanabilmesi adına şöyle bir kütüphane kuruyoruz:

composer require "zircote/swagger-php:2.*"


Sonrasında config/l5-swagger.php dosyasını açarak ufak değişiklikler yapıyoruz:

Swagger'ın 2.0 versiyonunu kullanacağımız için;

'swagger_version' => env('SWAGGER_VERSION', '2.0')

Swagger'da yapacağımız tanımlamaların bir yenileme işlemi sonrasında direkt olarak dokümantasyona yansıması için;

'generate_always' => env('L5_SWAGGER_GENERATE_ALWAYS', true)


Şimdi dokümantasyonumuzun başlangıcını atmak adına bir controller oluşturuyoruz:

php artisan make:controller DocController


Ve içeriğini şu şekilde dolduruyoruz:

/**
 * @SWG\Swagger(
 *     @SWG\Info(
 *          version="1.0.0",
 *          title="API",
 *          description="API Documentation"
 *     )
 * )
*/

Tahmin edeceğiniz üzere bu işlem dokümanımızın hemen başında api hakkında ön bir bilgilendirme yapmak amaçlıydı.


Şimdi şöyle bir işlem yapalım. 2 adet api yazalım. Birisi kullanıcının e-posta adresini ve parolasını alıp eğer doğruysa geriye token döndüren, yanlışsa "Unauthorized" şeklinde mesaj döndüren login apisi; diğeri header kısmında gönderilen token doğruysa geriye kullanıcının id, ad soyad ve yaş bilgisini döndüren, yanlışsa yine "Unauthorized" şeklinde mesaj döndüren profile apisi olsun. Sonrasında bu apileri Swagger ile dokümante edip yine Swagger üzerinden deneme yaparak çalıştıralım.


Öncelikle bir controller oluşturuyoruz:

php artisan make:controller UserController


routes/api.php dosyasında apilerimiz için gerekli route kısımlarını tanımlıyoruz:

Route::post('login', '[email protected]');
Route::get('profile', '[email protected]');


Ve artık UserController dosyamıza girebiliriz. Öncelikle login ve profile fonksiyonlarımızı yazalım:

login fonksiyonu;

public function login()
{
    $email = request()->email;
    $password = request()->password;
    if ($email == "[email protected]" && $password == "123123") {
        $user = (object)array(
                    'token' => str_random(10)
                );
        return response()->json($user, 200);
    } else {
        return response()->json('Unauthorized', 401);
    }
}

Çok basit bir şekilde kullanıcının e-posta adresini ve parolasını alıp doğrulama işlemi yaptık. Elbette kullanıcının bilgilerini veritabanında tutmalı ve bu fonksiyondaki işlemleri veritabanı sorgusuyla yapmalıydık. Ancak amacımız Swagger'ın kullanımını anlamak olduğundan işin veritabanı kısmına girmiyoruz.


profile fonksiyonu;

public function profile()
{
    $token = request()->header('token');
    if ($token == "testToken") {
        $user = (object)array(
            'user_id' => 1,
            'name_surname' => 'Test Kullanıcısı',
            'age' => 25
        );
        return response()->json($user, 200);
    } else {
        return response()->json('Unauthorized', 401);
    }
}

Burada da yine basitçe header kısmında yer alan token'a bakarak bir doğrulama işlemi yaptık.


Şimdi yazmış olduğumuz fonksiyonları Swagger ile dokümante etmek için gerekli tanımlamaları yapalım:

login fonksiyonu için tanımlama;

/** @SWG\Post(
 *     path="/api/login",
 *     tags={"Login"},
 *     summary="Login işlemi",
 *     description="Login işlemi",
 *     @SWG\Parameter(
 *          name="email",
 *          description="User e-mail address",
 *          required=true,
 *          type="string",
 *          in="query"
 *     ),
 *     @SWG\Parameter(
 *          name="password",
 *          description="User password",
 *          required=true,
 *          type="string",
 *          in="query"
 *     ),
 *     @SWG\Response(
 *          response=200,
 *          description="login is successful",
 *          @SWG\Schema(
 *              type="object",
 *              @SWG\Property(
 *                  property="token",
 *                  type="string"
 *             )
 *          )
 *     ),
 *     @SWG\Response(
 *          response=401,
 *          description="Unauthorized"
 *     )
 * )
*/

Tek tek tüm satırları açıklamaktan ziyade ufak bir özet geçelim:

  • Yapılacak isteğin metodunu belirterek işe başladık (@SWG\Post)
  • Api yolunu belirttik (path="/api/login")
  • Alacağı parametreleri belirttik (@SWG\Parameter) [ör: email parametresi, zorunlu alan, string veri tipinde ve query (body) kısmında gelmeli]
  • Dönebilecek cevapları belirttik (@SWG\Response) [ör: 200 status koduyla, object içerisinde string veri tipinde token]


İlk başta karışık gibi görünse de üzerine yoğunlaşıldığı zaman aslında ne kadar basit bir yazım şekli olduğu ortaya çıkıyor.

profile fonksiyonu için tanımlama;

/** @SWG\Get(
 *     path="/api/profile",
 *     tags={"Profil"},
 *     summary="Profil bilgisi",
 *     description="Profil bilgisi",
 *     @SWG\Parameter(
 *          name="token",
 *          description="User token",
 *          required=true,
 *          type="string",
 *          in="header"
 *     ),
 *     @SWG\Response(
 *          response=200,
 *          description="profile data",
 *          @SWG\Schema(
 *              type="object",
 *              @SWG\Property(
 *                  property="user_id",
 *                  type="integer"),
 *              @SWG\Property(
 *                  property="name_surname",
 *                  type="string"),
 *              @SWG\Property(
 *                  property="age",
 *                  type="integer"
 *             )
 *         )
 *     ),
 *     @SWG\Response(
 *          response=401,
 *          description="Unauthorized"
 *     )
 * )
 */

Yine bunun içinde ufak bir özet geçelim:

  • Yapılacak isteğin metodunu belirterek işe başladık (@SWG\Get)
  • Api yolunu belirttik (path="/api/profile")
  • Alacağı parametreleri belirttik (@SWG\Parameter) [ör: token parametresi, zorunlu alan, string veri tipinde ve header kısmında gelmeli]
  • Dönebilecek cevapları belirttik (@SWG\Response) [ör: 200 status koduyla, object içerisinde integer veri tipinde user_id, string veri tipinde name_surname ve integer veri tipinde age]


Şimdi de projemizi ayağa kaldırarak Swagger arayüzünde dokümanımızı görelim ve deneyelim:

php artisan serve


Tarayıcımızı açıyoruz ve şu linke gidiyoruz:

http://localhost:8000/api/documentation


Bizi şöyle bir arayüz karşılıyor:


login apisi için denememizi yapalım. Bunun için /api/login şeklinde belirtilen yere tıklıyoruz. Açılan kısımda sağ tarafta bulunan Try it out'a basıyoruz. Gerekli bilgileri doldurarak Execute'a basıyoruz.


Aşağıya doğru indiğimizde yapılan isteği ve gelen cevabı görüyoruz:


Aynı şekilde profile apisi için deneme yapabilirsiniz.


Umarım yararlı olmuştur. İyi çalışmalar.

Yusuf Borucu

Benim adım Yusuf. 1993 yılında Şanlırfa'da doğdum. 2015 yılında Bilecik Şeyh Edebali Üniversitesi'nde Bilgisayar Mühendisliği bölümünden mezun oldum. Şu anda özel bir şirkette Yazılım Geliştirici olarak çalışmaktayım. Yazılıma yönelik uğraştığım, sevdiğim ve ilgi duyduğum teknolojilerden bahsetmem gerekirse; Laravel, MySQL (mevcut çalıştığım şirkette uğraştıklarım). Asp.Net Mvc, MSSQL (önceden çal...

"Laravel'de Swagger ile Rest Api dokümantasyonu hazırlama" için hiç yorum yapılmadı.

Henüz yorum yapılmamış.

Yorum yap * E-posta adresiniz yayınlanmayacak.