Merhabalar, uzun zamandır siteme içerik girmiyordum. Aktif olarak bir firmada yazılım geliştirici olarak çalıştığım için boş zamanlarımı öğrenmeye ayırıyor paylaşımda bulunamıyordum. Vakit buldukça blogumu hem yazılımsal hem tasarımsal hem de içerik anlamında güncellemeye karar verdim. Bundan sonra elimden geldiğince daha çok vakit ayırarak blogumu güncel tutmaya özen göstereceğim.

Bu yazımın içeriğinde Laravel ile birlikte Swagger nasıl kullanırız kısaca ondan bahsedeceğim. İşlem boyunca "L5-Swagger" kullanacağım. Geliştirici olarak rol aldığım Laravel projelerinde bunu kullanmaktayım. L5-Swagger, "swagger-php" ve "swagger-ui" kullanılarak oluşturulmuş bir Laravel paketidir ve oldukça kullanışlıdır.

Swagger Laravel'de Nasıl Kullanılır

İlk olarak paketi composer ile projemize dahil ediyoruz.

composer require "darkaonline/l5-swagger" 

"config/app.php" dosyası içerisinde bulunan "providers" bölümüne aşağıdaki satırı ekliyoruz.

L5Swagger\L5SwaggerServiceProvider::class 

Sonrasında json formatında dökümanı oluşturmak ve güncellemek için aşağıdaki komutları çalıştırmamız yeterli. Her güncellemede çalıştırmanız gerekir.

php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"
php artisan l5-swagger:generate

"storage/api-docs" içerisinde api-docs.json şeklinde dökümanın json haline erişebilirsiniz. Dökümanı görüntülemek için ise "api/documentation" adresine girmeniz gerekmektedir.

Controller üzerinde de aşağıdaki örnekler gibi kullanabilirsiniz.

 /**
 * @OA\Post(
 *     path="/users",
 *     summary="Adds a new user - with oneOf examples",
 *     @OA\RequestBody(
 *         @OA\MediaType(
 *             mediaType="application/json",
 *             @OA\Schema(
 *                 @OA\Property(
 *                     property="id",
 *                     type="string"
 *                 ),
 *                 @OA\Property(
 *                     property="name",
 *                     type="string"
 *                 ),
 *                 @OA\Property(
 *                     property="phone",
 *                     oneOf={
 *                     	   @OA\Schema(type="string"),
 *                     	   @OA\Schema(type="integer"),
 *                     }
 *                 ),
 *                 example={"id": "a3fb6", "name": "Jessica Smith", "phone": 12345678}
 *             )
 *         )
 *     ),
 *     @OA\Response(
 *         response=200,
 *         description="OK",
 *         @OA\JsonContent(
 *             oneOf={
 *                 @OA\Schema(ref="#/components/schemas/Result"),
 *                 @OA\Schema(type="boolean")
 *             },
 *             @OA\Examples(example="result", value={"success": true}, summary="An result object."),
 *             @OA\Examples(example="bool", value=false, summary="A boolean value."),
 *         )
 *     )
 * )
 */

daha fazla örnek görüntülemek için mevcut repodaki örneklere yada swagger-php örneklerine bakabilirsiniz.