Bearer Token Laravel Sactum pada Dokumentasi API Swagger

Photo by Jozsef Hocza on Unsplash

Buat kamu yang sedang membuah rest API terkadang ada 1 pekerjaan tambahan yaitu membuah dokumentasi API itu sendiri. Kita dapat menggunakan aplikasi seperti postman dan kawan-kawannya,namun ada alternatif lain jika mau ingin membuat dokumentasi API. Memang dokumentasi yang lebih terstruktur dan rapi lebih baik dibuat dipostman tapi jika kamu ingin mencoba cara lain ada tool swagger.

Daripada kamu coding membuat API lalu masih membuat new folder lalu new request lalu menulis body dan parameter yang akan dikirim, kenapa tidak menuliskan langsung dokumentasinya langsung dalam source code kita.

Terdapat 1 kasus pada API yang diproteksi kita harus menyematkan bearer token untuk dapat mengakses endpoint tertentu, didalam postman kita bisa menambahkannya pada Tab Authorization lalu menginput Bearer Token, namun bagaimana jika menggunakan Swagger dimana kita harus meletakkan tokennya.

Step 1 : Install package

composer require DarkaOnLine/L5-Swagger

Step 2 : Publish ke config

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

Step 3 : edit config/l5-swagger.php

Tambahkan sactum pada securityScheme

'securityDefinitions' => [
  'securitySchemes' => [
    'sanctum' => [
         'type' => 'http',
         'description' => 'Laravel Sanctum token authentication',
         'scheme' => 'bearer',
         'bearerFormat' => 'JWT'
     ],
     ........         
   ],
],

Step 4 : Tambahkan code berikut pada file controller

Kode dibawah merupakan controller untuk menampilkan list User yang akan diproteksi dengan bearer token dari sactum.

security={ {"sanctum": {} }},

Kode lengkap

/**
     * @OA\Get(
     *      path="/api/v1/user",
     *      operationId="getUserList",
     *      tags={"Users"},
     *      summary="Get list of users",
     *      description="Menampilkan data list user",
     *      security={ {"sanctum": {} }},
     *      @OA\Response(
     *          response=200,
     *          description="Successful operation",
     *          @OA\MediaType(
     *           mediaType="application/json",
     *      )
     *      ),
     *      @OA\Response(
     *          response=401,
     *          description="Unauthenticated",
     *      ),
     *      @OA\Response(
     *          response=403,
     *          description="Forbidden"
     *      ),
     *      @OA\Response(
     *          response=400,
     *          description="Bad Request"
     *      ),
     *      @OA\Response(
     *          response=404,
     *          description="not found"
     *      ),
     *  )
     */
    public function index()
    {

Step 5 : Generate documentation lewat artisan

php artisan l5-swagger:generate

Step 6 : Buka alamat projek dokumentasi ( linkprojek/api/documentation )

Akan muncul menu authorize untuk memasukkan bearer token yang didapat ketika login

Sekarang kita dapat menambahkan kode bearer sactum kedalam dokumentasi API kita..

Terima kasih 😺