Khi làm việc với các dự án dùng api, chúng ta cần viết document cho các api để các bên liên quan(backend, frontend, app...) có thể làm việc độc lập với nhau. Thay vì sử dụng postman, chúng ta có thể dùng Laravel swagger để tạo document cho các api.
L5 Swagger
Khi sử dụng laravel chúng ta sẽ dùng packagist L5 Swagger để tạo document, dựa theo swagger php. Thư viện giúp tạo document api và có thể test trực tiếp api mà không cần dùng postman.
Install L5 Swagger
Cài đặt L5 Swagger cho laravel version > 6 với composer
composer require "darkaonline/l5-swagger"
Public l5-swagger tạo view và file config
$ php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"
Thiết lập các config cho thư viện trong file config/l5-swagger.php
<?php
return [
'default' => 'default',
'documentations' => [
'default' => [
'api' => [
'title' => 'L5 Swagger UI',
],
'routes' => [
/*
* Route for accessing api documentation interface
*/
'api' => 'api/documentation',
],
'paths' => [
/*
* Edit to include full URL in ui for assets
*/
'use_absolute_path' => env('L5_SWAGGER_USE_ABSOLUTE_PATH', true),
/*
* File name of the generated json documentation file
*/
'docs_json' => 'api-docs.json',
/*
* File name of the generated YAML documentation file
*/
'docs_yaml' => 'api-docs.yaml',
/*
* Set this to `json` or `yaml` to determine which documentation file to use in UI
*/
'format_to_use_for_docs' => env('L5_FORMAT_TO_USE_FOR_DOCS', 'json'),
/*
* Absolute paths to directory containing the swagger annotations are stored.
*/
'annotations' => [
//base_path('app'),
base_path('app') . '/Http/Controllers',
base_path('app') . '/Http/Requests',
base_path('app') . '/Http/Resources',
base_path('app') . '/L5Swagger',
],
],
],
],
'defaults' => [
'routes' => [
/*
* Route for accessing parsed swagger annotations.
*/
'docs' => 'docs',
/*
* Route for Oauth2 authentication callback.
*/
'oauth2_callback' => 'api/oauth2-callback',
/*
* Middleware allows to prevent unexpected access to API documentation
*/
'middleware' => [
'api' => [],
'asset' => [],
'docs' => [],
'oauth2_callback' => [],
],
/*
* Route Group options
*/
'group_options' => [],
],
'paths' => [
/*
* Absolute path to location where parsed annotations will be stored
*/
'docs' => storage_path('api-docs'),
/*
* Absolute path to directory where to export views
*/
'views' => base_path('resources/views/vendor/l5-swagger'),
/*
* Edit to set the api's base path
*/
'base' => env('L5_SWAGGER_BASE_PATH', null),
/*
* Edit to set path where swagger ui assets should be stored
*/
'swagger_ui_assets_path' => env('L5_SWAGGER_UI_ASSETS_PATH', 'vendor/swagger-api/swagger-ui/dist/'),
/*
* Absolute path to directories that should be exclude from scanning
* @deprecated Please use `scanOptions.exclude`
* `scanOptions.exclude` overwrites this
*/
'excludes' => [],
],
'scanOptions' => [
/**
* analyser: defaults to \OpenApi\StaticAnalyser .
*
* @see \OpenApi\scan
*/
'analyser' => null,
/**
* analysis: defaults to a new \OpenApi\Analysis .
*
* @see \OpenApi\scan
*/
'analysis' => null,
/**
* Custom query path processors classes.
*
* @link https://github.com/zircote/swagger-php/tree/master/Examples/schema-query-parameter-processor
* @see \OpenApi\scan
*/
'processors' => [
// new \App\SwaggerProcessors\SchemaQueryParameter(),
],
/**
* pattern: string $pattern File pattern(s) to scan (default: *.php) .
*
* @see \OpenApi\scan
*/
'pattern' => null,
/*
* Absolute path to directories that should be exclude from scanning
* @note This option overwrites `paths.excludes`
* @see \OpenApi\scan
*/
'exclude' => [],
/*
* Allows to generate specs either for OpenAPI 3.0.0 or OpenAPI 3.1.0.
* By default the spec will be in version 3.0.0
*/
'open_api_spec_version' => env('L5_SWAGGER_OPEN_API_SPEC_VERSION', \L5Swagger\Generator::OPEN_API_DEFAULT_SPEC_VERSION),
],
/*
* API security definitions. Will be generated into documentation file.
*/
'securityDefinitions' => [
'securitySchemes' => [
/*
* Examples of Security schemes
*/
/*
'api_key_security_example' => [ // Unique name of security
'type' => 'apiKey', // The type of the security scheme. Valid values are "basic", "apiKey" or "oauth2".
'description' => 'A short description for security scheme',
'name' => 'api_key', // The name of the header or query parameter to be used.
'in' => 'header', // The location of the API key. Valid values are "query" or "header".
],
'oauth2_security_example' => [ // Unique name of security
'type' => 'oauth2', // The type of the security scheme. Valid values are "basic", "apiKey" or "oauth2".
'description' => 'A short description for oauth2 security scheme.',
'flow' => 'implicit', // The flow used by the OAuth2 security scheme. Valid values are "implicit", "password", "application" or "accessCode".
'authorizationUrl' => 'http://example.com/auth', // The authorization URL to be used for (implicit/accessCode)
//'tokenUrl' => 'http://example.com/auth' // The authorization URL to be used for (password/application/accessCode)
'scopes' => [
'read:projects' => 'read your projects',
'write:projects' => 'modify projects in your account',
]
],
*/
/* Open API 3.0 support
'passport' => [ // Unique name of security
'type' => 'oauth2', // The type of the security scheme. Valid values are "basic", "apiKey" or "oauth2".
'description' => 'Laravel passport oauth2 security.',
'in' => 'header',
'scheme' => 'https',
'flows' => [
"password" => [
"authorizationUrl" => config('app.url') . '/oauth/authorize',
"tokenUrl" => config('app.url') . '/oauth/token',
"refreshUrl" => config('app.url') . '/token/refresh',
"scopes" => []
],
],
],
*/
'sanctum' => [ // Unique name of security
'type' => 'http', // Valid values are "basic", "apiKey" or "oauth2".
'description' => 'Enter token in format (Bearer )',
'name' => 'Authorization', // The name of the header or query parameter to be used.
'in' => 'header', // The location of the API key. Valid values are "query" or "header".
'scheme' => 'bearer',
],
],
'security' => [
/*
* Examples of Securities
*/
[
/*
'oauth2_security_example' => [
'read',
'write'
],
'passport' => []
*/
],
],
],
/*
* Set this to `true` in development mode so that docs would be regenerated on each request
* Set this to `false` to disable swagger generation on production
*/
'generate_always' => env('L5_SWAGGER_GENERATE_ALWAYS', false),
/*
* Set this to `true` to generate a copy of documentation in yaml format
*/
'generate_yaml_copy' => env('L5_SWAGGER_GENERATE_YAML_COPY', false),
/*
* Edit to trust the proxy's ip address - needed for AWS Load Balancer
* string[]
*/
'proxy' => false,
/*
* Configs plugin allows to fetch external configs instead of passing them to SwaggerUIBundle.
* See more at: https://github.com/swagger-api/swagger-ui#configs-plugin
*/
'additional_config_url' => null,
/*
* Apply a sort to the operation list of each API. It can be 'alpha' (sort by paths alphanumerically),
* 'method' (sort by HTTP method).
* Default is the order returned by the server unchanged.
*/
'operations_sort' => env('L5_SWAGGER_OPERATIONS_SORT', null),
/*
* Pass the validatorUrl parameter to SwaggerUi init on the JS side.
* A null value here disables validation.
*/
'validator_url' => null,
/*
* Swagger UI configuration parameters
*/
'ui' => [
'display' => [
/*
* Controls the default expansion setting for the operations and tags. It can be :
* 'list' (expands only the tags),
* 'full' (expands the tags and operations),
* 'none' (expands nothing).
*/
'doc_expansion' => env('L5_SWAGGER_UI_DOC_EXPANSION', 'none'),
/**
* If set, enables filtering. The top bar will show an edit box that
* you can use to filter the tagged operations that are shown. Can be
* Boolean to enable or disable, or a string, in which case filtering
* will be enabled using that string as the filter expression. Filtering
* is case-sensitive matching the filter expression anywhere inside
* the tag.
*/
'filter' => env('L5_SWAGGER_UI_FILTERS', true), // true | false
],
'authorization' => [
/*
* If set to true, it persists authorization data, and it would not be lost on browser close/refresh
*/
'persist_authorization' => env('L5_SWAGGER_UI_PERSIST_AUTHORIZATION', false),
'oauth2' => [
/*
* If set to true, adds PKCE to AuthorizationCodeGrant flow
*/
'use_pkce_with_authorization_code_grant' => false,
],
],
],
/*
* Constants which can be used in annotations
*/
'constants' => [
'L5_SWAGGER_CONST_HOST' => env('L5_SWAGGER_CONST_HOST', 'http://localhost'),
],
],
];
Cần chú ý khai báo L5_SWAGGER_CONST_HOST là endpoint của api, khai báo đường dẫn tuyệt đối cho thư mục chứa code các khai báo swagger(controller, request, resouces...), khai báo thêm scheme để không cần thêm Bearer trước token đăng nhập
// Khai báo endpoint
L5_SWAGGER_CONST_HOST="http://localhost"
// Khai báo các thư mục chứa khai báo swagger
'annotations' => [
//base_path('app'),
base_path('app') . '/Http/Controllers',
base_path('app') . '/Http/Requests',
base_path('app') . '/Http/Resources',
base_path('app') . '/L5Swagger',
],
// Thêm config scheme
'sanctum' => [ // Unique name of security
'type' => 'apiKey', // Valid values are "basic", "apiKey" or "oauth2".
'description' => 'Enter token in format (Bearer )',
'name' => 'Authorization', // The name of the header or query parameter to be used.
'in' => 'header', // The location of the API key. Valid values are "query" or "header".
'scheme' => 'bearer',
],
Define API document with l5 swagger
Thêm khai báo vào file App/Http/Controllers/controller.php
<?php
namespace App\Http\Controllers;
use Illuminate\Foundation\Auth\Access\AuthorizesRequests;
use Illuminate\Foundation\Bus\DispatchesJobs;
use Illuminate\Foundation\Validation\ValidatesRequests;
use Illuminate\Routing\Controller as BaseController;
/**
* @OA\Info(
* version="1.0",
* title="Example for response examples value"
* )
*/
/**
* @OA\Info(
* version="1.0.",
* title="Laravel Api Documentation",
* description="L5 Swagger",
* @OA\License(
* name="Apache 2.0",
* url="http://www.apache.org/licenses/LICENSE-2.0.html"
* )
* )
*
* @OA\Server(
* url=L5_SWAGGER_CONST_HOST,
* description="Demo API Server"
* )
*/
class Controller extends BaseController
{
use AuthorizesRequests, DispatchesJobs, ValidatesRequests;
}
Tạo document cho api đăng kí user, định nghĩa swagger trong controller Auth
<?php
namespace App\Http\Controllers\Api\V1;
use App\Exceptions\ApiException;
use App\Http\Controllers\Controller;
use App\Http\Requests\Auth\CreateUserRequest;
use App\Http\Resources\AuthResource;
use App\Models\User;
use Illuminate\Support\Facades\Hash;
class AuthController extends Controller
{
/**
* Register User
*
* @OA\Post(
* path="/api/v1/register",
* tags={"Auth"},
* @OA\RequestBody(
* required=true,
* @OA\JsonContent(
* ref="#/components/schemas/CreateUserRequest"
* )
* ),
* @OA\Response(
* response=200,
* description="Successful operation",
* @OA\JsonContent(ref="#/components/schemas/AuthResource")
* ),
* @OA\Response(
* response=401,
* description="Unauthenticated",
* ),
* @OA\Response(
* response=403,
* description="Forbidden"
* )
* )
* @param CreateUserRequest $request
* @return AuthResource
*/
public function createUser(CreateUserRequest $request): AuthResource
{
$user = User::create([
'name' => $request->name,
'email' => $request->email,
'password' => Hash::make($request->password)
]);
return new AuthResource($user);
}
}
Định nghĩa request body trong file request
<?php
namespace App\Http\Requests\Auth;
use Illuminate\Foundation\Http\FormRequest;
/**
* @OA\Schema(
* properties={
* @OA\Property(property="name", type="string", example="huunv"),
* @OA\Property(property="email", type="string", example="huunv@gmail.com"),
* @OA\Property(property="password", type="string", example="123456"),
* }
* )
*/
class CreateUserRequest extends FormRequest
{
/**
* Determine if the user is authorized to make this request.
*
* @return bool
*/
public function authorize()
{
return true;
}
/**
* Get the validation rules that apply to the request.
*
* @return array<string, mixed>
*/
public function rules()
{
return [
'name' => 'required',
'email' => 'required|email|unique:users,email',
'password' => 'required'
];
}
}
Định nghĩa response trả về trong file resource
<?php
namespace App\Http\Resources;
/**
* @OA\Schema(
* properties={
* @OA\Property(
* property="success",
* type="boolean",
* example="true"
* ),
* @OA\Property(
* property="data",
* type="object",
* @OA\Property(property="token", type="string", example="3|PXX3pewsSBbtJhJQXXuRZ1NiLHzTvD6Bv2TBUJjm"),
* @OA\Property(property="token_type", type="string", example="Bearer"),
* ),
* @OA\Property(
* property="message",
* type="string",
* example="success"
* )
* }
* )
*/
class AuthResource extends SuccessResource
{
/**
* Transform the resource into an array.
*
* @param \Illuminate\Http\Request $request
* @return array|\Illuminate\Contracts\Support\Arrayable|\JsonSerializable
*/
public function toArray($request)
{
return [
'token' => $this->createToken("api")->plainTextToken,
'token_type' => 'Bearer',
];
}
}
Như vậy là chúng ta đã định nghĩa xong api đăng kí user
// Api endpoint
http://localhost/api/v1/register
// Method
POST
// Request
name, email, password
// Response
trả về bearer token
How to use l5 swagger
Để tạo document chúng ta chỉ việc chạy command là xong
php artisan l5-swagger:generate
root@094dc8f9ff50:/var/www# php artisan l5-swagger:generate
Regenerating docs default
Kiểm tra api document với link
{domain}/api/documentation
// Example
http://localhost/api/documentation
Và đây là thành quả của chúng ta
Sử laravel L5 swagger chúng ta cũng có thể test api trực tiếp tại document luôn, mà không cần dùng postman. Click vào try it out để thử nhé
Đăng kí thử một user mới từ document
Kết quả chúng ta đã đăng kí người dùng thành công
Tống kết
Nhưng vậy là chúng ta đã tích hợp được l5 swagger cho ứng dụng laravel thành công, bài viết này mình sử dụng laravel 9. Hi vọng bài viết sẽ giúp ích cho mọi người. Thanks for reading...
Author
