Sebagai bagian dari QuickAdminPanel kami, kami juga membuat API. Namun tujuan Anda juga menyediakan dokumentasi untuk front-end siapa yang akan menggunakan API tersebut, bukan? OpenAPI (mis. Swagger) adalah standar terkenal untuk itu. Bagaimana cara menerapkannya pada proyek Laravel?
Pada artikel ini, kita akan memiliki bagian berikut:
- Intro Singkat: Apa itu OpenAPI dan Bagaimana Cara Kerjanya?
- Persiapan: Kode API Laravel Awal
- Menginstal Paket Laravel Swagger
- Menulis Komentar dan Menghasilkan Dokumentasi
Di akhir artikel, Anda akan menemukan link ke contoh repositori Github.
Intro Singkat: Apa itu OpenAPI dan Bagaimana Cara Kerjanya?
Pertama, beberapa kata tentang apa itu OpenAPI/Swagger.
Sebelumnya disebut Kesombongan (cukup sering disebut demikian bahkan sampai sekarang), OpenAPI adalah standar pendokumentasian API. Spesifikasinya tersedia di Github di sini.
Definisi resmi dari beranda mereka: “Spesifikasi OpenAPI: standar industri yang diadopsi secara luas untuk mendeskripsikan API modern.”
Perlu diingat bahwa ini bukan standar Laravel API. Bahkan tidak standar bahasa PHP. Ini skema API yang dapat digunakan untuk bahasa pemrograman apa pun. Ini seperti seperangkat aturan yang dapat disesuaikan dengan kerangka kerja Anda.
Khusus untuk Laravel, ada beberapa paket yang dibuat, dan kami akan menggunakan salah satunya: DarkaOnLine/L5-Swagger
Mari kita lihat hasil akhirnya – inilah halaman dokumentasi yang akan dihasilkan secara otomatis dari Anda komentar kode:
Di dalam halaman ini, Anda dapat mengklik item untuk memperluasnya dan mendapatkan informasi lebih lanjut.
Dan itu semua karena Anda telah menulis beberapa komentar, seperti ini:
class ProjectsApiController extends Controller
{
/**
* @OA\Get(
* path="/projects",
* operationId="getProjectsList",
* tags={"Projects"},
* summary="Get list of projects",
* description="Returns list of projects",
* @OA\Response(
* response=200,
* description="Successful operation",
* @OA\JsonContent(ref="#/components/schemas/ProjectResource")
* ),
* @OA\Response(
* response=401,
* description="Unauthenticated",
* ),
* @OA\Response(
* response=403,
* description="Forbidden"
* )
* )
*/
public function index()
{
abort_if(Gate::denies('project_access'), Response::HTTP_FORBIDDEN, '403 Forbidden');
return new ProjectResource(Project::with(['author'])->get());
}
Jadi, ini adalah ikhtisar singkatnya, sekarang mari kita bahas lebih dalam dan tunjukkan cara membuat dokumentasi langkah demi langkah.
Persiapan: Kode API Laravel Awal
Pertama, saya akan menunjukkan kode dasar struktur API, mungkin berguna untuk mempelajarinya bahkan jika Anda tidak berencana membuat dokumentasi.
Bayangkan Anda memiliki seorang model Proyek dan semua tindakan API untuk itu: indeks, simpan, perbarui, tampilkan, hancurkan.
Jadi, ini dia rute/api.php:
Route::group([
'prefix' => 'v1',
'as' => 'api.',
'namespace' => 'Api\V1\Admin',
'middleware' => ['auth:api']
], function () {
Route::apiResource('projects', 'ProjectsApiController');
});
Dalam contoh ini, kami menempatkan ProyekApiController di dalam V1/Admin subfolder.
Jadi inilah kode kita app/Http/Controllers/V1/Admin/ProjectsApiController.php:
namespace App\Http\Controllers\Api\V1\Admin;
use App\Http\Controllers\Controller;
use App\Http\Requests\StoreProjectRequest;
use App\Http\Requests\UpdateProjectRequest;
use App\Http\Resources\Admin\ProjectResource;
use App\Project;
use Gate;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;
class ProjectsApiController extends Controller
{
public function index()
{
abort_if(Gate::denies('project_access'), Response::HTTP_FORBIDDEN, '403 Forbidden');
return new ProjectResource(Project::with(['author'])->get());
}
public function store(StoreProjectRequest $request)
{
$project = Project::create($request->all());
return (new ProjectResource($project))
->response()
->setStatusCode(Response::HTTP_CREATED);
}
public function show(Project $project)
{
abort_if(Gate::denies('project_show'), Response::HTTP_FORBIDDEN, '403 Forbidden');
return new ProjectResource($project->load(['author']));
}
public function update(UpdateProjectRequest $request, Project $project)
{
$project->update($request->all());
return (new ProjectResource($project))
->response()
->setStatusCode(Response::HTTP_ACCEPTED);
}
public function destroy(Project $project)
{
abort_if(Gate::denies('project_delete'), Response::HTTP_FORBIDDEN, '403 Forbidden');
$project->delete();
return response(null, Response::HTTP_NO_CONTENT);
}
}
Berikut beberapa hal tambahan yang perlu kami sampaikan:
Ini salah satu file itu – app/Http/Resources/Admin/ProjectResource.php:
namespace App\Http\Resources\Admin;
use Illuminate\Http\Resources\Json\JsonResource;
class ProjectResource extends JsonResource
{
public function toArray($request)
{
return parent::toArray($request);
}
}
Juga, untuk validasi – app/Http/Requests/StoreProjectRequest.php:
namespace App\Http\Requests;
use Gate;
use Illuminate\Foundation\Http\FormRequest;
use Symfony\Component\HttpFoundation\Response;
class StoreProjectRequest extends FormRequest
{
public function authorize()
{
abort_if(Gate::denies('project_create'), Response::HTTP_FORBIDDEN, '403 Forbidden');
return true;
}
public function rules()
{
return [
'name' => [
'required',
],
];
}
}
Jadi, inilah awal kita. Sekarang, mari mulai membuat dokumentasi dengan OpenAPI.
Menginstal Paket Laravel Swagger
Salah satu paket paling populer untuk menghasilkan dokumentasi OpenAPI di Laravel adalah DarkaOnLine/L5-Swagger.
Jangan bingung dengan namanya – ini tidak mengubah bagian nama Swagger menjadi OpenAPI, tetapi sebenarnya mendukung kedua standar tersebut. Juga “L5” pada namanya juga tidak penting – Laravel 6 saat ini didukung dengan baik.
Jadi, kami menginstal paketnya:
composer require darkaonline/l5-swagger
Selanjutnya, mengikuti petunjuk instalasi di Readme, kami menerbitkan konfigurasi/tampilan dari Penyedia Layanan:
php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"
Akhirnya, kita punya config/l5-swagger.php file dengan banyak pilihan:
[
/*
|--------------------------------------------------------------------------
| Edit to set the api's title
|--------------------------------------------------------------------------
*/
'title' => 'L5 Swagger UI',
],
'routes' => [
/*
|--------------------------------------------------------------------------
| Route for accessing api documentation interface
|--------------------------------------------------------------------------
*/
'api' => 'api/documentation',
// ...
],
// ... many more options
/*
|--------------------------------------------------------------------------
| Uncomment to add constants which can be used in annotations
|--------------------------------------------------------------------------
*/
'constants' => [
'L5_SWAGGER_CONST_HOST' => env('L5_SWAGGER_CONST_HOST', '
],
];
Untuk contoh ini, kami akan mengedit judul dari ‘L5 Swagger UI’ ke ‘Projects API’, dan tambahkan ini ke dalamnya .env mengajukan:
L5_SWAGGER_CONST_HOST=
Dan kemudian kita harus meluncurkan perintah ajaib ini:
php artisan l5-swagger:generate
Itu harus menghasilkan file JSON, yang kemudian akan diubah menjadi halaman HTML.
Tapi, untuk saat ini, itu tidak akan menghasilkan apa-apa, sebab kami belum menambahkan komentar apa pun di mana pun. Baiklah?
Menulis Komentar dan Menghasilkan Dokumentasi
Ini mungkin bagian utama dari artikel ini – aturan tentang cara menulis komentar tersebut dan di mana tepatnya.
Paket ini akan memindai semua file Anda dan mencari pola komentar terkait OpenAPI.
Jadi, jenis komentar apa yang perlu kita tambahkan?
- Global: Komentar proyek
- Lokal: Komentar Pengontrol/Metode
- Virtual: Model, Validasi dan Respon komentar
Saya hanya akan mencantumkan komentarnya di sini, untuk informasi lebih lanjut tentang logikanya silakan merujuk ke contoh singkat di dalam paket Laravel, atau ke spesifikasi resmi OpenAPI secara detail.
Komentar Tipe 1: Global
Kita perlu memberikan informasi tentang keseluruhan proyek, dan untuk itu, kita membuat file terpisah – sebuah Controller kosong yang bahkan tidak akan digunakan di mana pun – app/Http/Controllers/Api/Controller.php:
class Controller
{
/**
* @OA\Info(
* version="1.0.0",
* title="Laravel OpenApi Demo Documentation",
* description="L5 Swagger OpenApi description",
* @OA\Contact(
* email="admin@admin.com"
* ),
* @OA\License(
* name="Apache 2.0",
* url="
* )
* )
*
* @OA\Server(
* url=L5_SWAGGER_CONST_HOST,
* description="Demo API Server"
* )
*
* @OA\Tag(
* name="Projects",
* description="API Endpoints of Projects"
* )
*/
}
Variabel-variabel ini akan membantu menghasilkan informasi utama di header halaman dokumentasi:
Komentar Tipe 2: Metode Pengontrol
Untuk mendeskripsikan setiap titik akhir API, kita perlu menambahkan anotasi komentar di atas setiap metode di Pengontrol API.
Jadi, inilah contoh lengkap kami app/Http/Controllers/Api/V1/Admin/ProjectsApiController.php:
class ProjectsApiController extends Controller
{
/**
* @OA\Get(
* path="/projects",
* operationId="getProjectsList",
* tags={"Projects"},
* summary="Get list of projects",
* description="Returns list of projects",
* @OA\Response(
* response=200,
* description="Successful operation",
* @OA\JsonContent(ref="#/components/schemas/ProjectResource")
* ),
* @OA\Response(
* response=401,
* description="Unauthenticated",
* ),
* @OA\Response(
* response=403,
* description="Forbidden"
* )
* )
*/
public function index()
{
abort_if(Gate::denies('project_access'), Response::HTTP_FORBIDDEN, '403 Forbidden');
return new ProjectResource(Project::with(['author'])->get());
}
/**
* @OA\Post(
* path="/projects",
* operationId="storeProject",
* tags={"Projects"},
* summary="Store new project",
* description="Returns project data",
* @OA\RequestBody(
* required=true,
* @OA\JsonContent(ref="#/components/schemas/StoreProjectRequest")
* ),
* @OA\Response(
* response=201,
* description="Successful operation",
* @OA\JsonContent(ref="#/components/schemas/Project")
* ),
* @OA\Response(
* response=400,
* description="Bad Request"
* ),
* @OA\Response(
* response=401,
* description="Unauthenticated",
* ),
* @OA\Response(
* response=403,
* description="Forbidden"
* )
* )
*/
public function store(StoreProjectRequest $request)
{
$project = Project::create($request->all());
return (new ProjectResource($project))
->response()
->setStatusCode(Response::HTTP_CREATED);
}
/**
* @OA\Get(
* path="/projects/{id}",
* operationId="getProjectById",
* tags={"Projects"},
* summary="Get project information",
* description="Returns project data",
* @OA\Parameter(
* name="id",
* description="Project id",
* required=true,
* in="path",
* @OA\Schema(
* type="integer"
* )
* ),
* @OA\Response(
* response=200,
* description="Successful operation",
* @OA\JsonContent(ref="#/components/schemas/Project")
* ),
* @OA\Response(
* response=400,
* description="Bad Request"
* ),
* @OA\Response(
* response=401,
* description="Unauthenticated",
* ),
* @OA\Response(
* response=403,
* description="Forbidden"
* )
* )
*/
public function show(Project $project)
{
abort_if(Gate::denies('project_show'), Response::HTTP_FORBIDDEN, '403 Forbidden');
return new ProjectResource($project->load(['author']));
}
/**
* @OA\Put(
* path="/projects/{id}",
* operationId="updateProject",
* tags={"Projects"},
* summary="Update existing project",
* description="Returns updated project data",
* @OA\Parameter(
* name="id",
* description="Project id",
* required=true,
* in="path",
* @OA\Schema(
* type="integer"
* )
* ),
* @OA\RequestBody(
* required=true,
* @OA\JsonContent(ref="#/components/schemas/UpdateProjectRequest")
* ),
* @OA\Response(
* response=202,
* description="Successful operation",
* @OA\JsonContent(ref="#/components/schemas/Project")
* ),
* @OA\Response(
* response=400,
* description="Bad Request"
* ),
* @OA\Response(
* response=401,
* description="Unauthenticated",
* ),
* @OA\Response(
* response=403,
* description="Forbidden"
* ),
* @OA\Response(
* response=404,
* description="Resource Not Found"
* )
* )
*/
public function update(UpdateProjectRequest $request, Project $project)
{
$project->update($request->all());
return (new ProjectResource($project))
->response()
->setStatusCode(Response::HTTP_ACCEPTED);
}
/**
* @OA\Delete(
* path="/projects/{id}",
* operationId="deleteProject",
* tags={"Projects"},
* summary="Delete existing project",
* description="Deletes a record and returns no content",
* @OA\Parameter(
* name="id",
* description="Project id",
* required=true,
* in="path",
* @OA\Schema(
* type="integer"
* )
* ),
* @OA\Response(
* response=204,
* description="Successful operation",
* @OA\JsonContent()
* ),
* @OA\Response(
* response=401,
* description="Unauthenticated",
* ),
* @OA\Response(
* response=403,
* description="Forbidden"
* ),
* @OA\Response(
* response=404,
* description="Resource Not Found"
* )
* )
*/
public function destroy(Project $project)
{
abort_if(Gate::denies('project_delete'), Response::HTTP_FORBIDDEN, '403 Forbidden');
$project->delete();
return response(null, Response::HTTP_NO_CONTENT);
}
}
Wah, rasanya BANYAK yang komentar ya?
Namun itulah cara yang benar dalam menyiapkan dokumentasi – Anda perlu menjelaskan semua metode, semua kasus, semua parameter, semua pengecualian.
Tipe Komentar 3: Model, Validasi dan Respon
Anda mungkin telah memperhatikan beberapa referensi ke file eksternal di komentar pada Kontroler di atas. Jadi apa itu Permintaan Proyek Toko di sana? Kami mendefinisikan semua aturan tersebut di folder kami yang disebut aplikasi/Virtuallihat daftar file:
Mari kita lihat bagian dalamnya app/Virtual/Models/Project.php:
/**
* @OA\Schema(
* title="Project",
* description="Project model",
* @OA\Xml(
* name="Project"
* )
* )
*/
class Project
{
/**
* @OA\Property(
* title="ID",
* description="ID",
* format="int64",
* example=1
* )
*
* @var integer
*/
private $id;
/**
* @OA\Property(
* title="Name",
* description="Name of the new project",
* example="A nice project"
* )
*
* @var string
*/
public $name;
/**
* @OA\Property(
* title="Description",
* description="Description of the new project",
* example="This is new project's description"
* )
*
* @var string
*/
public $description;
/**
* @OA\Property(
* title="Created at",
* description="Created at",
* example="2020-01-27 17:50:45",
* format="datetime",
* type="string"
* )
*
* @var \DateTime
*/
private $created_at;
/**
* @OA\Property(
* title="Updated at",
* description="Updated at",
* example="2020-01-27 17:50:45",
* format="datetime",
* type="string"
* )
*
* @var \DateTime
*/
private $updated_at;
/**
* @OA\Property(
* title="Deleted at",
* description="Deleted at",
* example="2020-01-27 17:50:45",
* format="datetime",
* type="string"
* )
*
* @var \DateTime
*/
private $deleted_at;
/**
* @OA\Property(
* title="Author ID",
* description="Author's id of the new project",
* format="int64",
* example=1
* )
*
* @var integer
*/
public $author_id;
/**
* @OA\Property(
* title="Author",
* description="Project author's user model"
* )
*
* @var \App\Virtual\Models\User
*/
private $author;
}
Lihat, kita perlu mendefinisikan setiap propertinya Proyek model, termasuk hubungannya dengan penulis.
Sekarang, bagaimana dengan permintaan validasi formulir? Melihat app/Virtual/StoreProjectRequest.php:
/**
* @OA\Schema(
* title="Store Project request",
* description="Store Project request body data",
* type="object",
* required={"name"}
* )
*/
class StoreProjectRequest
{
/**
* @OA\Property(
* title="name",
* description="Name of the new project",
* example="A nice project"
* )
*
* @var string
*/
public $name;
/**
* @OA\Property(
* title="description",
* description="Description of the new project",
* example="This is new project's description"
* )
*
* @var string
*/
public $description;
/**
* @OA\Property(
* title="author_id",
* description="Author's id of the new project",
* format="int64",
* example=1
* )
*
* @var integer
*/
public $author_id;
}
Hampir copy-paste kan?
Terakhir, kita perlu mendefinisikan Sumber Daya API, yang dalam kasus kita adalah “data” – in aplikasi/Virtual/Resources/ProjectResource.php:
/**
* @OA\Schema(
* title="ProjectResource",
* description="Project resource",
* @OA\Xml(
* name="ProjectResource"
* )
* )
*/
class ProjectResource
{
/**
* @OA\Property(
* title="Data",
* description="Data wrapper"
* )
*
* @var \App\Virtual\Models\Project[]
*/
private $data;
}
Dan, itulah akhirnya! Kita dapat menjalankan perintah artisan ini sekali lagi:
php artisan l5-swagger:generate
Ya!
Dan jika Anda mengeklik titik akhir mana pun, titik akhir tersebut akan diperluas dengan semua parameter yang Anda berikan, dan bahkan dengan contoh respons – itulah keindahan terbesarnya:
Terakhir, hal kecil yang menyenangkan di halaman dokumentasi ini adalah Anda dapat mengklik “Cobalah” (lihat kanan atas tangkapan layar di atas) dan ia akan mencoba menjalankan panggilan API tersebut. Namun perlu diingat bahwa Anda harus diautentikasi persis seperti permintaan API Anda.
Kesimpulan dan Alternatif “Lebih Cepat” untuk OpenAPI
Jika Anda seperti saya saat pertama kali membaca tentang OpenAPI, ada banyak sekali informasi yang harus diambil. Dan sepertinya membutuhkan banyak pekerjaan hanya untuk membuat dokumentasinya, bukan?
Namun jika Anda berurusan dengan proyek yang lebih besar, Anda pasti harus menghabiskan banyak waktu untuk dokumentasi, dan OpenAPI adalah standar bagi hampir semua orang saat ini, jadi berinvestasi di dalamnya akan berguna.
Ini tidak akan berlaku untuk proyek-proyek kecil, bahkan mungkin terdengar berlebihan. Jadi untuk itu, saya akan merekomendasikan paket Laravel lain, yang memerlukan lebih sedikit komentar untuk menghasilkan dokumentasi HTML yang kurang lebih mirip: mpociot/laravel-apidoc-generator
Seperti yang dijanjikan, repositori Github untuk artikel ini ada di sini: LaravelDaily/Laravel-OpenAPI-Swagger-Documentation-Example
News
Berita
News Flash
Blog
Technology
Sports
Sport
Football
Tips
Finance
Berita Terkini
Berita Terbaru
Berita Kekinian
News
Berita Terkini
Olahraga
Pasang Internet Myrepublic
Jasa Import China
Jasa Import Door to Door
Gaming center adalah sebuah tempat atau fasilitas yang menyediakan berbagai perangkat dan layanan untuk bermain video game, baik di PC, konsol, maupun mesin arcade. Gaming center ini bisa dikunjungi oleh siapa saja yang ingin bermain game secara individu atau bersama teman-teman. Beberapa gaming center juga sering digunakan sebagai lokasi turnamen game atau esports.
Comments are closed, but trackbacks and pingbacks are open.