Blog

Cara Membuat Dokumentasi Swagger dengan Swagger-PHP

Swagger-PHP alat ampuh buat dokumentasi API Swagger di PHP. Mudah dipasang & hasilkan dokumentasi Swagger untuk API Anda.

Ardianto Nugroho

Ardianto Nugroho

17 May 2025

Cara Membuat Dokumentasi Swagger dengan Swagger-PHP

Swagger-PHP selalu menjadi hal pertama yang terlintas dalam pikiran ketika memikirkan tentang menghasilkan spesifikasi Swagger untuk proyek php. Jadi, apa itu Swagger-PHP? Bagaimana cara membuat spesifikasi menggunakan Swagger-php? Dalam artikel ini, kami akan membahas pertanyaan-pertanyaan ini dan memperkenalkan Anda pada detailnya.

Apa itu Swagger-PHP

swagger-PHP adalah alat untuk menghasilkan dokumentasi API menggunakan Swagger (sekarang dikenal sebagai Spesifikasi OpenAPI) di PHP. swagger-php membantu pengembang PHP membuat dokumentasi API berdasarkan spesifikasi Swagger (OpenAPI). Alat ini dapat menghasilkan spesifikasi Swagger (OpenAPI) dari kode PHP. Ini memungkinkan pengembang untuk menentukan titik akhir API, permintaan, dan respons dalam kode, dan secara otomatis menghasilkan spesifikasi Swagger (OpenAPI).

Fitur-fitur Swagger-PHP

Swagger-PHP adalah alat yang ampuh yang digunakan untuk menghasilkan spesifikasi untuk OpenAPI versi 3.0 dan 3.1. Ia juga mampu merekam API menggunakan kode sumber PHP. Atribut anotasi yang digunakan oleh Swagger-php dapat berupa blok doc atau php 8.1, menjadikannya sangat fleksibel dan serbaguna.

Baik Anda bekerja dengan blok doc atau versi PHP terbaru, Swagger-php dapat membantu menyederhanakan proses pengembangan API Anda dan membuatnya lebih efisien secara keseluruhan.

Cara Instalasi dan Pengaturan di Swagger-PHP

Untuk mulai menggunakan Swagger-PHP, Anda perlu menginstalnya terlebih dahulu. Swagger-PHP dapat diinstal menggunakan Composer, pengelola dependensi untuk PHP.

Untuk menginstal Swagger-PHP, jalankan perintah berikut di terminal Anda:

composer require zircote/swagger-php

Setelah diinstal, Anda dapat mulai menggunakan Swagger-PHP untuk menghasilkan dokumentasi Swagger untuk API Anda.

Selanjutnya, Anda perlu menyiapkan Swagger-PHP dengan membuat instance Swagger baru dan mengonfigurasinya dengan informasi API Anda. Berikut adalah contoh cara menyiapkan Swagger-PHP:

require_once('vendor/autoload.php');

use Swagger\Annotations as SWG;

/**
 * @SWG\Swagger(
 *     basePath="/api",
 *     schemes={"http", "https"},
 *     @SWG\Info(
 *         version="1.0.0",
 *         title="My API",
 *         description="API documentation for My API",
 *         @SWG\Contact(name="My Company"),
 *         @SWG\License(name="MIT")
 *     )
 * )
 */

Dalam contoh ini, kami telah membuat instance Swagger baru dan mengonfigurasinya dengan informasi API kami, seperti jalur dasar, skema, dan info API (versi, judul, deskripsi, kontak, dan lisensi).

Setelah Anda menyiapkan Swagger-PHP, Anda dapat mulai menambahkan anotasi Swagger ke kode API Anda untuk menghasilkan dokumentasi Swagger. Kami akan membahas ini secara lebih rinci di bagian berikutnya.

Membuat Dokumentasi Swagger dengan Swagger-PHP

Swagger-PHP adalah pustaka PHP untuk menghasilkan dokumen Swagger. Di bagian ini, kita akan belajar cara membuat dokumentasi Swagger menggunakan Swagger-PHP.

Langkah 1. Mendefinisikan informasi API

Pertama, kita perlu mendefinisikan informasi API. Ini termasuk judul, deskripsi, versi, dll. dari API. Berikut ini adalah contoh:

$swagger = \Swagger\Swagger::make()
    ->info([
        'title' => 'My API',
        'description' => 'This is a sample API documentation.',
        'version' => '1.0.0'
    ]);

Langkah 2. Mendefinisikan titik akhir API

Selanjutnya, kita perlu mendefinisikan titik akhir API. Ini termasuk metode HTTP, jalur, parameter, dan respons untuk setiap titik akhir. Berikut ini adalah contoh:

$swagger = \Swagger\Swagger::make()
    ->info([
        'title' => 'My API',
        'description' => 'This is a sample API documentation.',
        'version' => '1.0.0'
    ])
    ->get('/users', [
        'summary' => 'Get a list of users.',
        'description' => 'Returns a list of users.',
        'responses' => [
            '200' => [
                'description' => 'A list of users.',
                'schema' => [
                    'type' => 'array',
                    'items' => [
                        '$ref' => '#/definitions/User'
                    ]
                ]
            ]
        ]
    ])
    ->post('/users', [
        'summary' => 'Create a new user.',
        'description' => 'Creates a new user.',
        'parameters' => [
            [
                'name' => 'user',
                'in' => 'body',
                'description' => 'The user to create.',
                'required' => true,
                'schema' => [
                    '$ref' => '#/definitions/User'
                ]
            ]
        ],
        'responses' => [
            '200' => [
                'description' => 'The created user.',
                'schema' => [
                    '$ref' => '#/definitions/User'
                ]
            ]
        ]
    ]);

Langkah 3. Mendefinisikan model data

Terakhir, kita perlu mendefinisikan model data. Ini termasuk atribut dan jenis setiap model. Berikut ini adalah contoh:

$swagger = \Swagger\Swagger::make()
    ->info([
        'title' => 'My API',
        'description' => 'This is a sample API documentation.',
        'version' => '1.0.0'
    ])
    ->get('/users', [
        'summary' => 'Get a list of users.',
        'description' => 'Returns a list of users.',
        'responses' => [
            '200' => [
                'description' => 'A list of users.',
                'schema' => [
                    'type' => 'array',
                    'items' => [
                        '$ref' => '#/definitions/User'
                    ]
                ]
            ]
        ]
    ])
    ->post('/users', [
        'summary' => 'Create a new user.',
        'description' => 'Creates a new user.',
        'parameters' => [
            [
                'name' => 'user',
                'in' => 'body',
                'description' => 'The user to create.',
                'required' => true,
                'schema' => [
                    '$ref' => '#/definitions/User'
                ]
            ]
        ],
        'responses' => [
            '200' => [
                'description' => 'The created user.',
                'schema' => [
                    '$ref' => '#/definitions/User'
                ]
            ]
        ]
    ])
    ->definitions([
        'User' => [
            'type' => 'object',
            'properties' => [
                'id' => [
                    'type' => 'integer',
                    'format' => 'int64'
                ],
                'name' => [
                    'type' => 'string'
                ],
                'email' => [
                    'type' => 'string'
                ]
            ]
        ]
    ]);

Langkah 4. Mengekspor dokumen Swagger

Terakhir, kita dapat mengeluarkan dokumentasi Swagger menggunakan kode berikut:

header('Content-Type: application/json');
echo $swagger->toJson();

Ini akan menghasilkan dokumen Swagger dalam format JSON yang dapat digunakan untuk menghasilkan dokumentasi API.

Mengintegrasikan Swagger UI dengan Swagger-PHP

Untuk sepenuhnya memanfaatkan manfaat dokumentasi Swagger, penting untuk memiliki antarmuka yang ramah pengguna untuk melihat dan berinteraksi dengan dokumentasi. Di sinilah Swagger-ui berperan. Swagger-UI adalah antarmuka berbasis web yang menyediakan pengalaman interaktif untuk melihat dan menguji dokumentasi Swagger.

Mengintegrasikan Swagger-UI dengan Swagger-PHP adalah proses yang mudah. Pertama, unduh versi terbaru Swagger-UI dari repositori GitHub resmi. Kemudian, ekstrak isi arsip yang diunduh ke direktori di server web Anda.

Selanjutnya, buat file PHP baru yang akan berfungsi sebagai titik masuk untuk Swagger-UI. Dalam file ini, sertakan file CSS dan JavaScript yang diperlukan untuk Swagger-UI, serta pustaka JavaScript Swagger-ui itu sendiri. Anda juga perlu menyertakan file JSON yang dihasilkan Swagger-PHP yang berisi dokumentasi API Anda.

<!DOCTYPE html>
<html>
<head>
  <title>Swagger UI</title>
  <link rel="stylesheet" type="text/css" href="path/to/swagger-ui.css">
  <script type="text/javascript" src="path/to/swagger-ui-bundle.js"></script>
  <script type="text/javascript" src="path/to/swagger-ui-standalone-preset.js"></script>
</head>
<body>
  <div id="swagger-ui"></div>
  <script type="text/javascript">
    window.onload = function() {
      // Build a system
      const ui = SwaggerUIBundle({
        url: "path/to/swagger-json.php",
        dom_id: '#swagger-ui',
        presets: [
          SwaggerUIBundle.presets.apis,
          SwaggerUIStandalonePreset
        ],
        layout: "BaseLayout"
      })
    }
  </script>
</body>
</html>

Dalam contoh di atas, ganti placeholder path/to dengan jalur sebenarnya ke file CSS dan JavaScript Swagger-UI, serta Swagger-PHP, file JSON yang dihasilkan.

Setelah Anda membuat file ini, Anda dapat mengakses Swagger-UI dengan menavigasi ke URL-nya di browser web Anda. Anda akan melihat antarmuka Swagger-ui yang berfungsi penuh yang menampilkan dokumentasi API Anda dan memungkinkan Anda berinteraksi dengannya.

Kesimpulannya, mengintegrasikan Swagger-UI dengan Swagger-PHP adalah proses sederhana yang sangat meningkatkan kegunaan dokumentasi API Anda. Dengan mengikuti langkah-langkah yang diuraikan di atas, Anda dapat dengan mudah membuat antarmuka yang ramah pengguna untuk dokumentasi API Anda yang akan memudahkan pengembang untuk memahami dan menggunakan API Anda.

Bagikan spesifikasi API

Setelah menghasilkan spesifikasi Swagger, saya sering membagikannya dengan anggota tim saya. Dalam kasus ini, kami sering berbagi dalam format Swagger JSON atau OpenAPI yaml, tetapi itu tampak agak ketinggalan zaman.

Di sini Apidog adalah alat manajemen API yang sempurna yang secara instan menghasilkan spesifikasi API yang sangat mudah dibaca berdasarkan data Swagger JSON atau YAML. Anda juga dapat dengan mudah membagikan spesifikasi API ini dengan fungsi berbagi API.

Apidog

Apidog juga menyediakan berbagai fungsi sebagai alat manajemen siklus hidup API.

Desain API dan pembuatan spesifikasi: Apidog adalah alat desain API termudah untuk digunakan, memungkinkan Anda untuk secara intuitif mendesain API tanpa kode, dan dengan nyaman menghasilkan spesifikasi OpenAPI dan Swagger.

Manajemen API dan pengujian unit: Apidog membuat pengujian unit sangat mudah karena Anda dapat secara efisien mengelola API Anda, mengirim permintaan API, dan memvalidasi respons.

Otomatisasi Pengujian API: Apidog juga mendukung pengujian otomatis dan siap untuk CI/CD. Dengan menggunakan fungsi ini untuk mengatur jumlah thread, dll., Anda dapat dengan mudah mengimplementasikan pengujian beban API dan otomatisasi pengujian API.

Kesimpulan

Kesimpulannya, Swagger-PHP adalah alat yang ampuh untuk menghasilkan dokumentasi Swagger untuk API berbasis PHP. Ini memungkinkan pengembang untuk dengan mudah mendokumentasikan API mereka dan membuatnya dapat diakses oleh pengembang lain. Selain itu, mengintegrasikan Swagger-UI dengan Swagger-php menyediakan antarmuka yang ramah pengguna untuk menjelajahi dan menguji API.

Berikut adalah beberapa sumber daya untuk pembelajaran lebih lanjut tentang Swagger-PHP:

Mengembangkan API dengan Apidog

Apidog adalah alat pengembangan API yang membantu Anda mengembangkan API dengan lebih mudah dan efisien.

Daftar gratisUnduh