Laravel projelerinde swagger ile döküman hazırlanması
Swagger, API’ler için detaylı döküman oluşturmamızı ve test edebilmemizi sağlayan bir yazılımdır.
Yazılım geliştirirken en önemli süreçlerden biri döküman hazırlanmasıdır. Döküman hazırlanması API servisi kullanacak diğer yazılımcılar ve projeye sonradan dahil olan kişiler için bir yol gösterici niteliği taşır ve test süreçlerini de kolaylaştırır.
Bu yazıda bir Laravel uygulaması üzerinde bazı paketler yardımıyla swagger dökümanı hazırlanmasını anlatacağım. Laravel projemizi oluşturduktan sonra aşağıdaki komutları çalıştırmamız gerekiyor.
composer require darkaonline/l5-swagger
composer require zircote/swagger-php
php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"Swagger-php paketi, php kodunun içinde swagger tanımları yapmamızı ve bunların algılanıp API belgelerine dönüştürülmesini sağlar.
L5-Swagger paketi, swagger-php ile swagger arayüzünün Laravel uygulaması üzerinde birleştirilip swagger ile ilgili ayarların Laravel uygulaması üzerinden daha kolay yönetilebilmesini sağlayan bir pakettir. Bu paketi ekledikten sonra config dosyasının altında l5-swagger.php adlı bir dosya oluşacaktır.
Bu yardımcı swagger paketleri sayesinde API fonksiyonlarının ve classlarının üzerinde tanımlamalar yapabiliriz. Bu tanımlamalar algılanıp json formata çevrilir ve api-docs.json adlı döküman dosyası oluşturulur.
Kategoriler üzerinde CRUD işlemleri yapan ve bunların CategoryController ve Category model sınıfları üzerinden yönetildiği bir API servisimiz olsun.
/**
* @OA\Get (
* path="/api/categories",
* tags={"Category"},
* summary="List all categories",
* @OA\Response(
* response=200,
* description="Get all categories",
* @OA\JsonContent(
* type="array",
* @OA\Items(ref="#/components/schemas/Category")
* )
* ),
* )
*/
public function index()
{
return Category::all();
}Fonksiyonlar veya sınıflar üzerinde bazı tanımlamalar yaptık.
- @OA\Get servise erişeceğimiz HTTP metodunun Get olduğunu belirtir.
- Path istek atılacak API servisin URL’ini belirtir.
- Ortak bir başlık altında toplamak istediğimiz tüm API servisleri aynı tags altında tanımlayabiliriz.
- Summary kısmında servisin kısaca ne yaptığı açıklanır.
- @OA\Response içinde API servisin nasıl bir response döneceği belirtilir. Biz burada bir json array’i döneceğini belirtmek için @OA\JsonContent kullandık ve type parametresini array olarak belirledik. Dönen array category objeleri içerdiği için bunu da @OA\Items altında Category Schema kullanarak ekledik.
Schema tanımını da category model sınıfının üzerinde aşağıdaki gibi yapabiliriz.
/**
* @OA\Schema (
* type="object",
* schema="Category",
* properties={
* @OA\Property(property="id", type="int"),
* @OA\Property(property="name", type="string"),
* @OA\Property(property="slug", type="string"),
* @OA\Property(property="crated_at", type="datetime"),
* @OA\Property(property="updated_at", type="datetime"),
* },
* )
*/
class Category extends Model
{
}Modelin döneceği parametreleri @OA\Property altında isim ve değişken tipleriyle birlikte tanımladık.
Tüm bu tanımlamalar yapıldıktan sonra api-docs.json dosyasının oluşturulması için aşağıdaki komut çalıştırılmalıdır.
php artisan l5-swaggerHer seferinde bu komutu çalıştırmak istemiyorsak değişikliklerin otomatik olarak algılanıp api-docs.json dosyasının güncellenmesi için env.php altına aşağıdaki satırı ekleyebiliriz.
L5_SWAGGER_GENERATE_ALWAYS=trueBu işlemler yapıldıktan sonra projemizdeki /api/documentation URL’ine giderek swagger dökümanına erişebiliriz. Bu tanımlardan sonra aşağıdaki gibi bir çıktıyla karşılaşırız.
Try it out butonuna tıklayarak servise istek atabilir ve sonucunu görebiliriz.
Bu tanımlar yapıldığında arka tarafta oluşan api-docs.json ise aşağıdaki gibidir. Ek paketleri kullanmadan bu json dosyasını elle oluşturarakta dökümanı hazırlayabiliriz ve fakat paket işimizi daha da kolaylaştırıyor.
{
"paths": {
"/api/categories": {
"get": {
"tags": [
"Category"
],
"summary": "List all categories",
"responses": {
"200": {
"description": "Get all categories",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Category"
}
}
}
}
}
}
},
}
"components": {
"schemas": {
"Category": {
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"crated_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"type": "object"
}
},
}Silme işlemi yapan bir API için ise swagger tanımlamaları aşağıdaki gibi olabilir.
/**
* @OA\Delete(
* path="/api/categories/{categoryId}",
* tags={"Category"},
* summary="Delete a category",
* @OA\Parameter (
* name="categoryId",
* description="id column of the category delete",
* required=true,
* @OA\Schema (type="integer")
* ),
* @OA\Response(
* response=200,
* description="Category deleted response",
* @OA\JsonContent(ref="#/components/schemas/DefaultResponse")
* ),
* )
*/
public function destroy(Category $category)
{
$response = $category->delete();
return $this->defaultResponse($response);
}- Farklı HTTP metodları için @OA\Post, @OA\Put, @OA\Delete gibi tanımlar mevcuttur.
- API parametre alıyorsa @OA\Parameter kullanılabilir.
- Alınan parametre path içinde {parameterName} şeklinde belirtilebilir.
Category CRUD servisleri ile ilgili tüm tanımlamaları bitirdiğimizde aşağıdaki gibi bir görüntü oluşacaktır. Bu sayede hem servislerin test edilmesi hem de nasıl çalıştığının anlaşılması gayet kolaylaşacaktır.
Bunlar dışında daha bir çok özellik bulunmaktadır. Bunların detaylarının bulunduğu ve yazıyı yazarken de faydalandığım kaynakları aşağıda paylaşıyorum. Okuduğunuz için teşekkür ederim.
Dökümanlar ve faydalı olabilecek linkler
