Source code aplikasi, template web, dan ebook. Unduh dari akun setelah bayar. Lihat produk

Blog / Dokumentasi / Membuat Dokumentasi API dan Pa...
Dokumentasi

Membuat Dokumentasi API dan Panduan Instalasi Source Code Laravel untuk Pelanggan

AD

Admin HijrahKreativa

Penulis

19 Oct 2026
14 min read
12 views

Menyerahkan proyek Laravel dengan profesional: dokumentasi API otomatis, panduan instalasi yang bisa diikuti non-developer, skrip pengecekan, dan paket rilis yang bersih.

Pendahuluan

Proyek selesai, kode berjalan sempurna di komputer Anda, lalu pelanggan menghubungi: "Cara install-nya bagaimana? Endpoint-nya apa saja?" Beberapa jam habis untuk menjelaskan satu per satu lewat chat. Masalah ini sangat umum, dan hampir seluruhnya bisa dicegah dengan dokumentasi yang baik.

Dokumentasi serah terima (handover) bukan sekadar formalitas. Ia:

  • mengurangi pertanyaan dukungan setelah proyek selesai,
  • membuat tim pelanggan atau developer berikutnya mandiri,
  • melindungi Anda dari klaim "tidak jalan di server kami",
  • menaikkan kesan profesional dan nilai proyek.

Artikel ini membahas dua dokumen utama: dokumentasi API (untuk developer yang mengonsumsi API) dan panduan instalasi (untuk siapa pun yang menjalankan aplikasi), plus cara menyiapkan paket source code yang rapi.

Bagian A: Dokumentasi API

Pilih Alat: Scribe atau Scramble

Dua paket populer untuk Laravel:

Scribe Scramble
Pendekatan Anotasi docblock + contoh respons nyata Membaca kode dan tipe secara statis (hampir tanpa anotasi)
Keluaran Halaman HTML, koleksi Postman, OpenAPI Dokumentasi OpenAPI dengan UI interaktif
Cocok untuk Dokumentasi dengan deskripsi dan contoh lengkap Dokumentasi cepat dari Form Request dan API Resource
Kekuatan Kontrol penuh atas isi Sangat sedikit kerja manual

Keduanya baik. Di bawah, Scribe dipakai sebagai contoh utama karena menghasilkan file statis yang mudah diserahkan ke pelanggan, lalu Scramble dibahas singkat sebagai alternatif.

1. Instal Scribe

composer require --dev knuckleswtf/scribe
php artisan vendor:publish --tag=scribe-config

Atur config/scribe.php seperlunya:

return [
    'title' => 'Dokumentasi API Toko Online',
    'description' => 'Panduan integrasi API untuk mitra dan developer.',
    'base_url' => env('APP_URL', 'https://api.contoh-domain.com'),

    'type' => 'static',                 // 'static' = file HTML, 'laravel' = disajikan oleh aplikasi

    'routes' => [
        [
            'match' => [
                'prefixes' => ['api/*'],
                'domains' => ['*'],
            ],
            'include' => [],
            'exclude' => ['api/internal/*'],      // jangan dokumentasikan endpoint internal
        ],
    ],

    'auth' => [
        'enabled' => true,
        'default' => false,
        'in' => 'bearer',
        'name' => 'Authorization',
        'use_value' => env('SCRIBE_AUTH_KEY'),
        'placeholder' => '{TOKEN_ANDA}',
        'extra_info' => 'Dapatkan token lewat endpoint **POST /api/login**.',
    ],

    'postman' => ['enabled' => true],
    'openapi' => ['enabled' => true],
];

2. Anotasi Controller

Scribe membaca docblock, validasi Form Request, dan API Resource.

// app/Http/Controllers/Api/ProductController.php
namespace App\Http\Controllers\Api;

/**
 * @group Produk
 *
 * Endpoint untuk mengelola katalog produk.
 */
class ProductController extends Controller
{
    /**
     * Daftar produk
     *
     * Mengambil daftar produk aktif dengan paginasi.
     *
     * @queryParam page integer Nomor halaman. Example: 1
     * @queryParam per_page integer Jumlah data per halaman (maks 50). Example: 15
     * @queryParam search string Cari berdasarkan nama atau SKU. Example: gamis
     *
     * @apiResourceCollection App\Http\Resources\ProductResource
     * @apiResourceModel App\Models\Product paginate=15
     */
    public function index(Request $request)
    {
        $products = Product::query()
            ->where('is_active', true)
            ->when($request->search, fn ($q, $s) => $q->where('name', 'like', "%{$s}%"))
            ->paginate(min($request->integer('per_page', 15), 50));

        return ProductResource::collection($products);
    }

    /**
     * Detail produk
     *
     * @urlParam product integer required ID produk. Example: 12
     *
     * @apiResource App\Http\Resources\ProductResource
     * @apiResourceModel App\Models\Product
     *
     * @response 404 {"message": "Produk tidak ditemukan."}
     */
    public function show(Product $product)
    {
        return new ProductResource($product);
    }

    /**
     * Tambah produk
     *
     * @authenticated
     *
     * @response 201 scenario="Berhasil" {"data": {"id": 13, "name": "Produk Baru"}}
     * @response 422 scenario="Validasi gagal" {"message": "The name field is required.", "errors": {"name": ["The name field is required."]}}
     */
    public function store(StoreProductRequest $request)
    {
        $product = Product::create($request->validated());

        return (new ProductResource($product))->response()->setStatusCode(201);
    }
}

Dokumentasikan parameter body lewat Form Request:

// app/Http/Requests/StoreProductRequest.php
public function rules(): array
{
    return [
        'name'  => ['required', 'string', 'max:150'],
        'price' => ['required', 'integer', 'min:0'],
        'stock' => ['required', 'integer', 'min:0'],
    ];
}

public function bodyParameters(): array
{
    return [
        'name'  => ['description' => 'Nama produk.',                       'example' => 'Gamis Premium'],
        'price' => ['description' => 'Harga dalam rupiah, tanpa desimal.', 'example' => 250000],
        'stock' => ['description' => 'Jumlah stok tersedia.',              'example' => 40],
    ];
}

Gunakan contoh yang realistis pada Example: dan example. Pelanggan akan menyalin nilai ini saat mencoba.

3. Hasilkan Dokumentasi

php artisan scribe:generate
Processing route: GET api/products
Processing route: GET api/products/{product}
Processing route: POST api/products
Wrote HTML docs and assets to: public/docs/
Generating Postman collection
Wrote Postman collection to public/docs/collection.json
Wrote OpenAPI specification to public/docs/openapi.yaml

Hasilnya:

public/docs/
├── index.html          ← halaman dokumentasi
├── collection.json     ← koleksi Postman
└── openapi.yaml        ← spesifikasi OpenAPI

Untuk contoh respons nyata, Scribe dapat memanggil endpoint saat men-generate (response calls). Jangan arahkan ke database production, dan pakai database khusus dokumentasi atau data factory agar tidak mengubah data sungguhan.

Alternatif: Scramble (hampir tanpa anotasi)

composer require dedoc/scramble

Buka /docs/api pada aplikasi, dan dokumentasi sudah muncul dari route, Form Request, dan API Resource. Perluas deskripsi dengan docblock biasa. Ekspor spesifikasinya dengan:

php artisan scramble:export

Secara bawaan, Scramble hanya tampil di lingkungan non-production. Atur akses di AppServiceProvider bila ingin menampilkannya untuk pelanggan:

use Dedoc\Scramble\Scramble;
use Illuminate\Support\Facades\Gate;

Gate::define('viewApiDocs', fn ($user = null) => in_array($user?->email, ['admin@contoh-domain.com']));

4. Isi yang Wajib Ada di Dokumentasi API

Selain daftar endpoint, pastikan hal-hal ini tercakup (tulis di bagian pendahuluan Scribe lewat config/scribe.php atau file .scribe/intro.md):

# Pendahuluan

## Base URL
`https://api.contoh-domain.com/api/v1`

## Autentikasi
Gunakan token Bearer. Sertakan header pada setiap request:

    Authorization: Bearer {TOKEN_ANDA}
    Accept: application/json

## Format Respons
Semua respons berformat JSON. Contoh sukses:

    { "data": { ... } }

Contoh error:

    { "message": "Pesan error", "errors": { "field": ["detail"] } }

## Kode Status
| Kode | Arti |
|---|---|
| 200 / 201 | Berhasil / dibuat |
| 401 | Token tidak ada atau tidak valid |
| 403 | Tidak punya izin |
| 404 | Data tidak ditemukan |
| 422 | Validasi gagal |
| 429 | Terlalu banyak request |

## Batas Laju (Rate Limit)
60 request per menit per token. Header `X-RateLimit-Remaining` menunjukkan sisa kuota.

## Paginasi
Gunakan `?page=` dan `?per_page=` (maksimal 50).

## Versi
Versi saat ini `v1`. Perubahan yang tidak kompatibel akan dirilis sebagai `v2`.

Dokumentasikan juga contoh cURL untuk endpoint utama:

curl -X GET "https://api.contoh-domain.com/api/v1/products?per_page=5" \
  -H "Authorization: Bearer {TOKEN_ANDA}" \
  -H "Accept: application/json"

Dan pastikan konfigurasi benar-benar sesuai dengan dokumentasi:

// routes/api.php
Route::prefix('v1')->middleware('throttle:60,1')->group(function () {
    Route::post('login', [AuthController::class, 'login']);

    Route::middleware('auth:sanctum')->group(function () {
        Route::apiResource('products', ProductController::class);
    });
});

5. Jaga Agar Dokumentasi Tidak Basi

Dokumentasi yang tidak cocok dengan kode lebih buruk daripada tidak ada. Masukkan generasi dokumentasi ke proses rilis:

# .github/workflows/docs.yml
name: Docs
on:
  push:
    branches: [main]

jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: shivammathur/setup-php@v2
        with: { php-version: '8.3' }
      - run: composer install --no-interaction --prefer-dist
      - run: cp .env.example .env && php artisan key:generate
      - run: php artisan scribe:generate
      - uses: actions/upload-artifact@v4
        with:
          name: api-docs
          path: public/docs

Bagian B: Panduan Instalasi Source Code

Panduan instalasi yang baik bisa diikuti oleh orang yang tidak mengenal proyek Anda. Uji dengan satu aturan: apakah seseorang bisa menjalankannya hanya dengan membaca file ini, tanpa bertanya?

Struktur Dokumen INSTALL.md

Letakkan di root proyek bersama README.md. Berikut kerangka yang bisa langsung dipakai.

# Panduan Instalasi - Toko Online v1.4.0

## 1. Kebutuhan Sistem

| Komponen | Versi |
|---|---|
| PHP | 8.2 atau lebih baru (disarankan 8.3) |
| Ekstensi PHP | bcmath, ctype, curl, fileinfo, gd, intl, mbstring, openssl, pdo_mysql, tokenizer, xml, zip |
| Database | MySQL 8.0+ atau MariaDB 10.6+ |
| Composer | 2.x |
| Node.js | 20 LTS (hanya bila build aset sendiri) |
| Web server | Nginx atau Apache (document root ke folder `public`) |

## 2. Instalasi

1. Ekstrak paket ke folder server, misalnya `/var/www/toko`.
2. Masuk ke folder proyek:

       cd /var/www/toko

3. Pasang dependensi:

       composer install --no-dev --optimize-autoloader

4. Salin file konfigurasi dan buat kunci aplikasi:

       cp .env.example .env
       php artisan key:generate

5. Edit `.env` (lihat bagian 3).
6. Buat database kosong, lalu jalankan migrasi dan data awal:

       php artisan migrate --force
       php artisan db:seed --force

7. Buat tautan penyimpanan dan cache konfigurasi:

       php artisan storage:link
       php artisan optimize

8. Atur izin folder:

       chmod -R 775 storage bootstrap/cache

9. Buka aplikasi di browser dan login (lihat bagian 4).

## 3. Konfigurasi `.env`

| Variabel | Keterangan | Contoh |
|---|---|---|
| `APP_URL` | Alamat aplikasi | `https://toko.contoh.com` |
| `APP_ENV` | Isi `production` | `production` |
| `APP_DEBUG` | **Harus** `false` di production | `false` |
| `DB_DATABASE` | Nama database | `toko` |
| `DB_USERNAME` / `DB_PASSWORD` | Akun database | - |
| `MAIL_*` | Pengaturan SMTP untuk email | - |
| `QUEUE_CONNECTION` | `database` atau `redis` | `database` |

## 4. Akun Awal

| Peran | Email | Password |
|---|---|---|
| Administrator | admin@contoh.com | (diberikan terpisah) |

**Segera ganti password setelah login pertama.**

## 5. Proses Latar Belakang

Aplikasi membutuhkan dua proses agar email dan tugas terjadwal berjalan.

**Scheduler** - tambahkan ke cron:

    * * * * * cd /var/www/toko && php artisan schedule:run >> /dev/null 2>&1

**Queue worker** - jalankan dengan Supervisor (contoh konfigurasi di `docs/supervisor.conf`).

## 6. Memeriksa Instalasi

    php artisan app:check-install

## 7. Pembaruan ke Versi Baru

    php artisan down
    # ganti file aplikasi (jangan timpa .env dan folder storage)
    composer install --no-dev --optimize-autoloader
    php artisan migrate --force
    php artisan optimize:clear && php artisan optimize
    php artisan queue:restart
    php artisan up

## 8. Pemecahan Masalah

| Masalah | Solusi |
|---|---|
| Halaman putih / error 500 | Lihat `storage/logs/laravel.log`, periksa izin `storage` |
| 404 di semua halaman selain beranda | Document root harus ke folder `public`, dan rewrite aktif |
| Gambar tidak tampil | Jalankan `php artisan storage:link` |
| Email tidak terkirim | Periksa `MAIL_*` dan pastikan queue worker berjalan |
| `Class not found` setelah update | `composer dump-autoload -o` lalu `php artisan optimize:clear` |

## 9. Dukungan

Email: dukungan@contoh.com
Sertakan: versi aplikasi, pesan error, dan cuplikan `storage/logs/laravel.log`.

Perintah Pemeriksa Instalasi

Daripada meminta pelanggan memeriksa satu per satu, sediakan perintah Artisan yang melaporkan masalah dengan jelas.

php artisan make:command CheckInstall
// app/Console/Commands/CheckInstall.php
namespace App\Console\Commands;

use Illuminate\Console\Command;
use Illuminate\Support\Facades\{DB, Storage};

class CheckInstall extends Command
{
    protected $signature = 'app:check-install';
    protected $description = 'Memeriksa kesiapan instalasi aplikasi';

    public function handle(): int
    {
        $rows = [];
        $fail = false;

        $check = function (string $name, bool $ok, string $hint = '') use (&$rows, &$fail) {
            $rows[] = [$name, $ok ? 'OK' : 'GAGAL', $ok ? '' : $hint];
            $fail = $fail || ! $ok;
        };

        $check('PHP >= 8.2', version_compare(PHP_VERSION, '8.2.0', '>='), 'Versi saat ini '.PHP_VERSION);

        foreach (['bcmath', 'curl', 'fileinfo', 'gd', 'intl', 'mbstring', 'openssl', 'pdo_mysql', 'xml', 'zip'] as $ext) {
            $check("Ekstensi {$ext}", extension_loaded($ext), "Aktifkan ekstensi {$ext}");
        }

        $check('APP_KEY terisi', filled(config('app.key')), 'Jalankan php artisan key:generate');
        $check('APP_DEBUG nonaktif', ! config('app.debug'), 'Set APP_DEBUG=false di production');

        try {
            DB::connection()->getPdo();
            $check('Koneksi database', true);
            $check('Migrasi sudah dijalankan', \Schema::hasTable('migrations'), 'Jalankan php artisan migrate');
        } catch (\Throwable $e) {
            $check('Koneksi database', false, 'Periksa DB_* di .env');
        }

        $check('storage dapat ditulis', is_writable(storage_path()), 'chmod -R 775 storage');
        $check('bootstrap/cache dapat ditulis', is_writable(base_path('bootstrap/cache')), 'chmod -R 775 bootstrap/cache');
        $check('Tautan storage ada', is_link(public_path('storage')), 'Jalankan php artisan storage:link');

        $this->table(['Pemeriksaan', 'Status', 'Saran'], $rows);

        $fail ? $this->error('Ada masalah yang perlu diperbaiki.') : $this->info('Semua pemeriksaan lolos.');

        return $fail ? self::FAILURE : self::SUCCESS;
    }
}

Contoh keluarannya:

+--------------------------------+--------+-----------------------------------+
| Pemeriksaan                    | Status | Saran                             |
+--------------------------------+--------+-----------------------------------+
| PHP >= 8.2                     | OK     |                                   |
| Ekstensi gd                    | GAGAL  | Aktifkan ekstensi gd              |
| APP_KEY terisi                 | OK     |                                   |
| APP_DEBUG nonaktif             | GAGAL  | Set APP_DEBUG=false di production |
| Koneksi database               | OK     |                                   |
| storage dapat ditulis          | OK     |                                   |
+--------------------------------+--------+-----------------------------------+
Ada masalah yang perlu diperbaiki.

Dengan ini, pesan dukungan berubah dari "tidak jalan" menjadi "ini hasil check-install saya".

.env.example yang Lengkap

File ini dokumentasi paling sering dibaca. Pastikan semua variabel yang dipakai ada, dengan nilai aman dan komentar.

APP_NAME="Toko Online"
APP_ENV=production
APP_KEY=
APP_DEBUG=false
APP_URL=https://toko.contoh.com

# Database
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=
DB_USERNAME=
DB_PASSWORD=

# Email (SMTP)
MAIL_MAILER=smtp
MAIL_HOST=
MAIL_PORT=587
MAIL_USERNAME=
MAIL_PASSWORD=
MAIL_FROM_ADDRESS="noreply@contoh.com"
MAIL_FROM_NAME="${APP_NAME}"

# Queue: database (sederhana) atau redis (lebih cepat)
QUEUE_CONNECTION=database

# Payment gateway (isi sesuai akun Anda)
PAYMENT_SERVER_KEY=
PAYMENT_CLIENT_KEY=
PAYMENT_IS_PRODUCTION=false

Jangan pernah mengisi .env.example dengan kredensial asli.

Bagian C: Menyiapkan Paket Source Code

1. Bersihkan Sebelum Dikemas

Hal yang tidak boleh ikut diserahkan:

  • .env (berisi rahasia Anda atau server Anda)
  • storage/logs/*, cache, dan session
  • node_modules/ dan vendor/ (kecuali Anda sengaja menyertakan vendor untuk pelanggan tanpa akses Composer)
  • Kunci API, token, dan kredensial lain yang tertinggal di kode
  • File .git bila repository tidak ikut diserahkan

Cari rahasia yang tertinggal sebelum mengemas:

grep -rniE "(api[_-]?key|secret|password|token)\s*[=:]\s*['\"][^'\"]{8,}" app config routes database resources --include=*.php
git log --all --oneline -S"PASSWORD" | head

2. Buat Paket dengan git archive

git archive hanya menyertakan file yang dilacak Git dan menghormati .gitattributes, sehingga hasilnya bersih.

# .gitattributes
/tests            export-ignore
/.github          export-ignore
/.gitignore       export-ignore
/.gitattributes   export-ignore
/phpunit.xml      export-ignore
/docs/internal    export-ignore
git archive --format=zip --prefix=toko-online-v1.4.0/ -o toko-online-v1.4.0.zip v1.4.0
$ unzip -l toko-online-v1.4.0.zip | tail -n 3
   ...
   1284  files

Pada Windows PowerShell, perintahnya sama selama Git terpasang:

git archive --format=zip --prefix=toko-online-v1.4.0/ -o toko-online-v1.4.0.zip v1.4.0

3. Beri Versi dan Catatan Perubahan

Gunakan semantic versioning (MAJOR.MINOR.PATCH) dan sertakan CHANGELOG.md.

# Changelog

## [1.4.0] - 2026-10-19
### Ditambahkan
- Endpoint `GET /api/v1/orders` dengan filter status.
### Diubah
- Batas `per_page` produk menjadi 50.
### Diperbaiki
- Email konfirmasi terkirim dua kali pada pembayaran ulang.
### Catatan Pembaruan
- Jalankan `php artisan migrate --force` (ada 2 migrasi baru).

Tandai rilis di Git:

git tag -a v1.4.0 -m "Rilis 1.4.0"
git push origin v1.4.0

4. Struktur Paket Serah Terima

toko-online-v1.4.0/
├── README.md              ← gambaran proyek singkat
├── INSTALL.md             ← panduan instalasi
├── CHANGELOG.md           ← riwayat perubahan
├── LICENSE.md             ← ketentuan lisensi penggunaan
├── .env.example
├── app/ ...
├── docs/
│   ├── api/               ← hasil scribe (HTML, Postman, OpenAPI)
│   ├── supervisor.conf    ← contoh konfigurasi worker
│   ├── nginx.conf         ← contoh konfigurasi web server
│   └── erd.png            ← diagram database
└── ...

Menyertakan contoh konfigurasi Nginx dan Supervisor menghemat banyak pertanyaan, karena bagian inilah yang paling sering salah di sisi pelanggan.

Bagian D: Uji Dokumentasi Anda

Dokumentasi yang belum pernah diuji hampir pasti ada yang salah. Lakukan uji sederhana ini sebelum menyerahkan:

  1. Siapkan mesin atau container bersih tanpa proyek Anda.
  2. Ikuti INSTALL.md persis, baris demi baris, tanpa pengetahuan tambahan.
  3. Catat setiap langkah yang membingungkan, dan perbaiki dokumennya (bukan hanya langsung diselesaikan).
  4. Jalankan php artisan app:check-install sampai semua lolos.
  5. Coba tiga endpoint utama dari koleksi Postman yang dihasilkan.
  6. Minta satu orang yang bukan pembuat proyek untuk mengikutinya.

Uji cepat dengan Docker, bila Anda memakainya:

docker run --rm -it -v "$(pwd)":/app -w /app composer:2 \
  composer install --no-dev --optimize-autoloader

Checklist Serah Terima

Dokumentasi API

  • ☐ Semua endpoint publik terdokumentasi dengan parameter, contoh request, dan contoh respons.
  • ☐ Bagian pendahuluan menjelaskan base URL, autentikasi, format error, kode status, rate limit, dan versi.
  • ☐ Contoh memakai data realistis, dan koleksi Postman atau OpenAPI disertakan.
  • ☐ Endpoint internal tidak ikut terdokumentasi.
  • ☐ Dokumentasi dihasilkan ulang dari kode versi yang diserahkan.

Panduan instalasi

  • ☐ Kebutuhan sistem (PHP, ekstensi, database) tertulis lengkap dengan versi.
  • ☐ Langkah instalasi berurutan dan bisa disalin-tempel.
  • ☐ .env.example lengkap, tanpa kredensial asli.
  • ☐ Akun awal dan instruksi mengganti password tercantum.
  • ☐ Proses latar belakang (cron dan queue worker) dijelaskan, beserta contoh konfigurasinya.
  • ☐ Ada panduan pembaruan versi dan tabel pemecahan masalah.
  • ☐ Perintah app:check-install tersedia.

Paket source code

  • ☐ Tidak ada .env, log, kunci API, atau data pelanggan di dalam paket.
  • ☐ Paket dibuat dari tag versi tertentu, lengkap dengan CHANGELOG.md.
  • ☐ Lisensi dan ketentuan penggunaan jelas.
  • ☐ Dokumentasi sudah diuji pada lingkungan bersih.

Penutup

Dokumentasi yang baik adalah bagian dari produk, bukan pelengkap. Otomatiskan sebisa mungkin: biarkan Scribe atau Scramble menjaga dokumentasi API tetap sinkron dengan kode, sediakan perintah pemeriksa instalasi, dan buat paket rilis dengan git archive. Lalu satu langkah terakhir yang sering dilewatkan: ikuti sendiri panduan Anda di mesin bersih. Waktu yang dihabiskan di sana jauh lebih murah daripada puluhan pesan dukungan setelah serah terima.

Bagikan artikel:

Artikel lainnya