PHP LUMEN SERVICE DOCS
PHP LUMEN SERVICE DOCS
1. Mempersiap Doc Generator
Hal pertama yang harus dilakukan adalah mempersiapkan docs Generator, untuk membuat docs generator kita akan menggunakan swagger-ui. Langsung saja install swagger plug-in dengan menuliskan ini pada terminal : composer require zircote/swagger-phpSetelah plug-in terinstall, buat file app/Console/Commands/SwaggerDocScanner.php
dan tulis code seperti dibawah ini:
<?php
namespace App\Console\Commands;
use Illuminate\Console\Command;
class SwaggerDocScanner extends Command
{
protected $signature = 'swaggerdoc:scan';
public function handle()
{
$path = dirname(dirname(__DIR__));
$outputPath = dirname(dirname(dirname(__DIR__))) . DIRECTORY_SEPARATOR . 'public/swaggerdoc.json';
$this->info('Scanning' . $path);
$openApi = \OpenApi\scan($path);
header('Content-Type: aplication/json');
file_put_contents($outputPath, $openApi->toJson());
$this->info('Output' . $outputPath);
}
}
Lalu buka file app/Console/Kernel.php, tambahkan code pada $protected $command seperti ini \App\Console\Commands\SwaggerDocScanner::class
Setelah itu buat tampilan User Interface, buat file public/api-docs.html, dan tulis code seperti dibawah ini:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>My Api Documentation</title>
<link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@3/swagger-ui.css">
</head>
<body>
<div id="swagger-ui"></div>
<script src="//unpkg.com/swagger-ui-dist@3/swagger-ui-standalone-preset.js"></script>
<script src="//unpkg.com/swagger-ui-dist@3/swagger-ui-bundle.js"></script>
<script>
(function() {
SwaggerUIBundle({
url: "swaggerdoc.json",
dom_id: '#swagger-ui',
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIStandalonePreset
],
layout: "StandaloneLayout"
});
})();
</script>
</body>
</html>
Run Lumen Serve, Kemudian buka http://localhost:8000/api-docs.html
2. Dokumentasi API Get Request
Kemudian membuat Dokumentasi API (Get Request), Hal yang harus dilakukan yaitu buka file app/Http/Controllers/Controller.php, tambahkan code seperti ini diatas class Controller
/**
* Class Controller
* @package App\Http\Controllers
* @OA\OpenApi(
* @OA\Info(
* version="1.0.0",
* title="Lumen Service App Doc",
* @OA\License(name="TEDC")
* ),
* @OA\Server(
* description="API server",
* url="http://localhost:8000"
* ),
* )
*/
Kemudian buka file app/Http/Controllers/Pub/PostsController.php, tambakan code diatas function index seperti dibawah ini
/**
* @OA\Get(
* path="/public/posts",
* summary="Get public posts",
* @OA\Parameter(name="page",
* in="query",
* required=false,
* @OA\Schema(type="number")
* ),
* @OA\Response(
* response=200,
* description="OK"
* )
* )
*/
/**
* Display a listing of the resource.
*
* @return \Illuminate\Http\Response
*/
Pada terminal jalankan command dibawah ini, Setiap kali kita mengubah anotasi docs, harus menjalankan command dibawah ini agar terupdate docsnya : php artisan swaggerdoc:scan
pada browser buka http://localhost:8000/api-docs.html
Jika di klik pada Button GET akan seperti ini
3. Dokumentasi API Post Request
Disini kita akan membuat Docs Post Request, buka file app/Http/Controllers/AuthController.php, tambahkan code seperti dibawah ini diatas function register
/**
* @OA\Post(
* path = "/auth/register",
* summary = "Register new user",
* tags = {"Authentication"},
* @OA\RequestBody(
* @OA\MediaType(
* mediaType = "aplication/json",
* @OA\Schema(
* @OA\Property(
* property = "name",
* type = "string"
* ),
* @OA\Property(
* property = "email",
* type = "string"
* ),
* @OA\Property(
* property = "role",
* type = "string"
* ),
* @OA\Property(
* property = "password",
* type = "string"
* ),
* @OA\Property(
* property = "password_confirmation",
* type = "string"
* ),
* example = {
* "name": "Username",
* "email": "user@email.com",
* "role": "editor",
* "password": "user",
* "password_confirmation": "user"
* }
* )
* )
* ),
* @OA\Response(
* response = 200,
* description = "OK"
* )
* )
*/
Lalu jalankan command php artisan swaggerdoc:scan agar docs terupdate di UI, lalu buka lagi pada browser
Jika di klik pada button POST akan seperti ini
Komentar
Posting Komentar