Membuat Dokumentasi API dengan Swagger di Laravel 9

Halo sahabat koding, selamat membaca di blog embuncode ya 😁 kali ini saya akan berbagi bagaimana cara membuat dokumentasi API dengan Swagger di Laravel 9.

1. Install Projek Laravel 

composer create-project laravel/laravel example-app
 
cd example-app

2. Install Package Swagger 

    https://github.com/DarkaOnLine/L5-Swagger

composer require darkaonline/l5-swagger

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

3. Buat Folder dengan nama API di dalam folder Controllers.

4. Buat File di dalam folder API misalkan dengan nama KategoriBeritaController.php

5. Kemudian Ketik untuk membuat Dokumentasi API misalkan menampilkan List Kategori Berita.

     
    /**
    *    @OA\Get(
    *       path="/kategori-berita",
    *       tags={"Berita"},
    *       operationId="kategoriBerita",
    *       summary="Kategori Berita",
    *       description="Mengambil Data Kategori Berita",
    *       @OA\Response(
    *           response="200",
    *           description="Ok",
    *           @OA\JsonContent
    *           (example={
    *               "success": true,
    *               "message": "Berhasil mengambil Kategori Berita",
    *               "data": {
    *                   {
    *                   "id": "1",
    *                   "nama_kategori": "Pendidikan",
    *                  }
    *              }
    *          }),
    *      ),
    *  )
    */
    public function listKategoriBerita() {
        return 'true';
    }

6. Tambahkan @OA\Info() pada file Controller.php yang terdapat di dalam folder Controllers.

    <?php

    namespace App\Http\Controllers;

    

    use Illuminate\Foundation\Auth\Access\AuthorizesRequests;

    use Illuminate\Foundation\Bus\DispatchesJobs;

    use Illuminate\Foundation\Validation\ValidatesRequests;

    use Illuminate\Routing\Controller as BaseController;

    /**

    * @OA\Info(

    * version="1.0.0",

    * title="Dokumentasi API",

    * description="Lorem Ipsum",

    * @OA\Contact(

    * email="hi.wasissubekti02@gmail.com"

    * ),

    * @OA\License(

    * name="Apache 2.0",

    * url="http://www.apache.org/licenses/LICENSE-2.0.html"

    * )

    * )

    *

    * @OA\Server(

    * url=L5_SWAGGER_CONST_HOST,

    * description="Demo API Server"

    * )

    */

    class Controller extends BaseController

    {

    use AuthorizesRequests, DispatchesJobs, ValidatesRequests;

    }

7. Ubah URL untuk mengakses API, silahkan buka file l5-swagger.php yang terdapat di dalam folder config, dibagian bawah ubah menjadi seperti ini.

    

    'constants' => [

    'L5_SWAGGER_CONST_HOST' =>

        env('L5_SWAGGER_CONST_HOST', 'http://localhost:8000/api/v1'),

    ],

8. Buat Route untuk menampilkan kategori berita, dengan cara lakukan perubahan pada file api.php yang terdapat di dalam folder routes seperit dibawah  ini.

      

    <?php

    use Illuminate\Support\Facades\Route;

    use App\Http\Controllers\API\KategoriBeritaController;

    /*

    |--------------------------------------------------------------------------

|     API Routes

|    --------------------------------------------------------------------------

|

|     Here is where you can register API routes for your application. These

|     routes are loaded by the RouteServiceProvider within a group which

|     is assigned the "api" middleware group. Enjoy building your API!

|

    */

    Route::group(['prefix' => 'v1'], function () {

    Route::get('kategori-berita', [KategoriBeritaController::class, 'listKategoriBerita']);

    });

9. Selanjutkan lakukan generate Documentation API dengan cara :

php artisan l5-swagger:generate

10. Periksa dokumentasi API pada browser dengan mengetikkan URL

http://localhost:8000/api/documentation

dan pastikan projek laravel telah dijalankan dengan perintah php artisan serve.

11. Maka jika berhasil akan tampil seperti berikut.

referensi:

https://swagger.io/solutions/api-documentation/

https://laravel.com/