Membuat Dokumentasi API dan Panduan Instalasi Source Code Laravel untuk Pelanggan
Admin HijrahKreativa
Penulis
Source code aplikasi, template web, dan ebook. Unduh dari akun setelah bayar. Lihat produk
Admin HijrahKreativa
Penulis
Menyerahkan proyek Laravel dengan profesional: dokumentasi API otomatis, panduan instalasi yang bisa diikuti non-developer, skrip pengecekan, dan paket rilis yang bersih.
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:
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.
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.
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],
];
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.
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.
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']));
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);
});
});
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
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?
INSTALL.mdLetakkan 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`.
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 LengkapFile 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.
Hal yang tidak boleh ikut diserahkan:
.env (berisi rahasia Anda atau server Anda)storage/logs/*, cache, dan sessionnode_modules/ dan vendor/ (kecuali Anda sengaja menyertakan vendor untuk pelanggan tanpa akses Composer).git bila repository tidak ikut diserahkanCari 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
git archivegit 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
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
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.
Dokumentasi yang belum pernah diuji hampir pasti ada yang salah. Lakukan uji sederhana ini sebelum menyerahkan:
INSTALL.md persis, baris demi baris, tanpa pengetahuan tambahan.php artisan app:check-install sampai semua lolos.Uji cepat dengan Docker, bila Anda memakainya:
docker run --rm -it -v "$(pwd)":/app -w /app composer:2 \
composer install --no-dev --optimize-autoloader
Dokumentasi API
Panduan instalasi
.env.example lengkap, tanpa kredensial asli.app:check-install tersedia.Paket source code
.env, log, kunci API, atau data pelanggan di dalam paket.CHANGELOG.md.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.
Sebelumnya
Checklist Audit Keamanan Website Laravel Menggunakan OWASP ZAP dan OWASP Top 10
Berikutnya
Membangun Sistem Pre-Order Laravel: Alur Produk, DP, Pelunasan, Produksi, dan Pengiriman
Dokumen ini menjelaskan prosedur konfigurasi autentikasi SSH Key antara server Ubuntu dan GitHub untuk memungkinkan server melakukan operasi Git, seperti clone, pull, dan fetch tanpa menggunakan username dan password akun GitHub.
Peta jalan arsitektur dari satu server hingga banyak server: tahapan pertumbuhan dan sinyal kapan naik tahap, prinsip yang sebaiknya diterapkan sejak awal (stateless, asinkron, data ber-tenant), read replica, pengelolaan data yang terus tumbuh, degradasi yang anggun saat layanan bermasalah, feature...
Menyiapkan lingkungan uji yang jujur, mengukur satu endpoint dengan ApacheBench, mensimulasikan perilaku pengguna sungguhan dengan k6 (skenario, threshold, autentikasi token), menelusuri penyebab request lambat dengan Telescope, memantau server selama pengujian, serta menulis laporan hasil dan angga...
Bagaimana Octane membuat Laravel lebih cepat dengan mem-boot aplikasi sekali dan menyimpannya di memori, apa yang sebenarnya dipercepat (dan yang tidak), risiko kebocoran state antar-request yang wajib dipahami, cara memeriksa kode agar aman untuk Octane, pemasangan dengan FrankenPHP di production,...
03 Nov 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
HijrahKreativa
Kami balas secepatnya
Masuk dulu untuk chat dengan tim kami. Riwayat chat Anda tersimpan di akun.
Masuk