Write API Document for project using Laravel

Thursday, 13/02/2020

Tram Ho

Hi everybody. I am currently developing a project that combines Laravel API and reactjs and makes it easy to coordinate between the frontend and backend teams and needs project documents to easily maintain, develop or hand over the project to The next development team should have a project to write documents for the API, after a while of learning and applying, I would like to share some knowledge with everyone. Regarding writing documents for laravel API, I use packet Laravel API Documentation Generator

first . Introducing the package and installation

Laravel API Documentation Generator is a generate API Document package that supports laravel. The Packege currently has nearly 2500star and more than 400 forks and is still under development. This package requires Laravel> = 5.7 and PHP> = 7.2 To install into the Laravel project, run the composer command:

Setting

Run the command to install the library
composer require --dev mpociot/laravel-apidoc-generator
Publish the configuration file by running the command:
php artisan vendor:publish --provider="MpociotApiDocApiDocGeneratorServiceProvider" --tag=apidoc-config
The configuration file of the package will be located in /config/apidoc.php
Run the following command to create API docs
php artisan apidoc:generate
So we have just created the default API docs to be able to customize and write more details for the API docs we will edit as follows

Configuration

The configuration file of the package will be located in /config/apidoc.php. The explanation of this config is as follows:
type: The document type, if selected as static, the document will be an HTML file located in public / docs, if selected laravel, the document will be a blade file located in resources / views / apidoc.
route: to fix it as laravel
base_url: base API URL, default is config (‘app.url’)
postman: install post man collection
enabled: the default is true. will create postman collection
name: top of collection
description: description for the collection
strategies: services to parse API docs
logo: API docs logo, standard size is 230 x 52
default_group: The default group of endpoints does not have the @group attribute
example_languages: programming language for examples
fractal: learn more at: https://fractal.thephpleague.com
routes: includes groups for setting API documents

<span class="token single-quoted-string string">'routes'</span> <span class="token operator">=</span> <span class="token operator">&gt;</span> <span class="token punctuation">[</span>
    <span class="token punctuation">[</span>
        <span class="token comment">// Những endpoint match điều kiện này sẽ được áp dụng các config bên dưới</span>
        <span class="token single-quoted-string string">'match'</span> <span class="token operator">=</span> <span class="token operator">&gt;</span> <span class="token punctuation">[</span>
            <span class="token comment">// match theo domain</span>
            <span class="token single-quoted-string string">'domains'</span> <span class="token operator">=</span> <span class="token operator">&gt;</span> <span class="token punctuation">[</span>
                <span class="token single-quoted-string string">'*'</span> <span class="token punctuation">,</span>
                <span class="token comment">// 'domain1.*',</span>
            <span class="token punctuation">]</span> <span class="token punctuation">,</span>
            <span class="token comment">// match theo prefix</span>
            <span class="token single-quoted-string string">'prefixes'</span> <span class="token operator">=</span> <span class="token operator">&gt;</span> <span class="token punctuation">[</span>
                <span class="token single-quoted-string string">'*'</span> <span class="token punctuation">,</span>
                <span class="token comment">// 'users/*',</span>
            <span class="token punctuation">]</span> <span class="token punctuation">,</span>
        <span class="token punctuation">]</span> <span class="token punctuation">,</span>
        <span class="token comment">// include những endpoint không match các điều kiện trên</span>
        <span class="token single-quoted-string string">'include'</span> <span class="token operator">=</span> <span class="token operator">&gt;</span> <span class="token punctuation">[</span>
            <span class="token comment">// 'users.index', 'healthcheck*'</span>
        <span class="token punctuation">]</span> <span class="token punctuation">,</span>
        <span class="token comment">// exclude những endpoint match các điều kiện trên</span>
        <span class="token single-quoted-string string">'exclude'</span> <span class="token operator">=</span> <span class="token operator">&gt;</span> <span class="token punctuation">[</span>
            <span class="token comment">// 'users.create', 'admin.*'</span>
        <span class="token punctuation">]</span> <span class="token punctuation">,</span>
        <span class="token comment">// thiết lập các quy tắc được áp dụng vào API Docs</span>
        <span class="token single-quoted-string string">'apply'</span> <span class="token operator">=</span> <span class="token operator">&gt;</span> <span class="token punctuation">[</span>
            <span class="token comment">// Header</span>
            <span class="token single-quoted-string string">'headers'</span> <span class="token operator">=</span> <span class="token operator">&gt;</span> <span class="token punctuation">[</span>
                <span class="token single-quoted-string string">'Content-Type'</span> <span class="token operator">=</span> <span class="token operator">&gt;</span> <span class="token single-quoted-string string">'application/json'</span> <span class="token punctuation">,</span>
                <span class="token single-quoted-string string">'Accept'</span> <span class="token operator">=</span> <span class="token operator">&gt;</span> <span class="token single-quoted-string string">'application/json'</span> <span class="token punctuation">,</span>
                <span class="token comment">// 'Authorization' =&gt; 'Bearer {token}',</span>
                <span class="token comment">// 'Api-Version' =&gt; 'v2',</span>
            <span class="token punctuation">]</span> <span class="token punctuation">,</span>
            <span class="token comment">// Nếu API Docs không có ví dụ của response trả về, package sẽ tự generate response theo config bên dưới</span>
            <span class="token single-quoted-string string">'response_calls'</span> <span class="token operator">=</span> <span class="token operator">&gt;</span> <span class="token punctuation">[</span>
                <span class="token comment">// method được áp dụng. '*' cho tất cả hoặc để trống để tắt tính năng này</span>
                <span class="token single-quoted-string string">'methods'</span> <span class="token operator">=</span> <span class="token operator">&gt;</span> <span class="token punctuation">[</span> <span class="token single-quoted-string string">'GET'</span> <span class="token punctuation">]</span> <span class="token punctuation">,</span>
                <span class="token comment">// Các biến được set cho API call</span>
                <span class="token single-quoted-string string">'config'</span> <span class="token operator">=</span> <span class="token operator">&gt;</span> <span class="token punctuation">[</span>
                    <span class="token single-quoted-string string">'app.env'</span> <span class="token operator">=</span> <span class="token operator">&gt;</span> <span class="token single-quoted-string string">'documentation'</span> <span class="token punctuation">,</span>
                    <span class="token single-quoted-string string">'app.debug'</span> <span class="token operator">=</span> <span class="token operator">&gt;</span> <span class="token boolean">false</span> <span class="token punctuation">,</span>
                    <span class="token comment">// 'service.key' =&gt; 'value',</span>
                <span class="token punctuation">]</span> <span class="token punctuation">,</span>
                <span class="token comment">// Cookie được gửi theo API call</span>
                <span class="token single-quoted-string string">'cookies'</span> <span class="token operator">=</span> <span class="token operator">&gt;</span> <span class="token punctuation">[</span>
                    <span class="token comment">// 'name' =&gt; 'value'</span>
                <span class="token punctuation">]</span> <span class="token punctuation">,</span>
                <span class="token comment">// query parameter được gửi theo API call.</span>
                <span class="token single-quoted-string string">'queryParams'</span> <span class="token operator">=</span> <span class="token operator">&gt;</span> <span class="token punctuation">[</span>
                    <span class="token comment">// 'key' =&gt; 'value',</span>
                <span class="token punctuation">]</span> <span class="token punctuation">,</span>
                <span class="token comment">// body parameter được gửi theo API call.</span>
                <span class="token single-quoted-string string">'bodyParams'</span> <span class="token operator">=</span> <span class="token operator">&gt;</span> <span class="token punctuation">[</span>
                    <span class="token comment">// 'key' =&gt; 'value',</span>
                <span class="token punctuation">]</span> <span class="token punctuation">,</span>
            <span class="token punctuation">]</span> <span class="token punctuation">,</span>
        <span class="token punctuation">]</span> <span class="token punctuation">,</span>
    <span class="token punctuation">]</span> <span class="token punctuation">,</span>
<span class="token punctuation">]</span> <span class="token punctuation">,</span>

'routes' = > [

[

// Những endpoint match điều kiện này sẽ được áp dụng các config bên dưới

'match' = > [

// match theo domain

'domains' = > [

'*' ,

// 'domain1.*',

] ,

// match theo prefix

'prefixes' = > [

'*' ,

// 'users/*',

] ,

// include những endpoint không match các điều kiện trên

'include' = > [

// 'users.index', 'healthcheck*'

] ,

// exclude những endpoint match các điều kiện trên

'exclude' = > [

// 'users.create', 'admin.*'

] ,

// thiết lập các quy tắc được áp dụng vào API Docs

'apply' = > [

// Header

'headers' = > [

'Content-Type' = > 'application/json' ,

'Accept' = > 'application/json' ,

// 'Authorization' => 'Bearer {token}',

// 'Api-Version' => 'v2',

] ,

// Nếu API Docs không có ví dụ của response trả về, package sẽ tự generate response theo config bên dưới

'response_calls' = > [

// method được áp dụng. '*' cho tất cả hoặc để trống để tắt tính năng này

'methods' = > [ 'GET' ] ,

// Các biến được set cho API call

'config' = > [

'app.env' = > 'documentation' ,

'app.debug' = > false ,

// 'service.key' => 'value',

] ,

// Cookie được gửi theo API call

'cookies' = > [

// 'name' => 'value'

] ,

// query parameter được gửi theo API call.

'queryParams' = > [

// 'key' => 'value',

] ,

// body parameter được gửi theo API call.

'bodyParams' = > [

// 'key' => 'value',

] ,

Write the Document API

To write an API document, go to the method in the controller that the route needs to write the document pointing to. And write above that method as I write below for the index method of the list page of the user list:

 <span class="token comment">/**
     * api/users
     *
     * This api to call list user.
     * param search name, email
     *
     * Example:
     * http://localhost:8001/api/users?search%5Bname%5D=thinh&amp;search%5Bemail%5D=nguyen
     *
     */</span>
    <span class="token keyword">public</span> <span class="token keyword">function</span> <span class="token function">index</span> <span class="token punctuation">(</span> Request <span class="token variable">$request</span> <span class="token punctuation">)</span>
    <span class="token punctuation">{</span>
        <span class="token variable">$searchParams</span> <span class="token operator">=</span> <span class="token variable">$request</span> <span class="token operator">-</span> <span class="token operator">&gt;</span> <span class="token property">search</span> <span class="token punctuation">;</span>
        <span class="token variable">$perPage</span> <span class="token operator">=</span> <span class="token function">config</span> <span class="token punctuation">(</span> <span class="token single-quoted-string string">'paginate.perPage'</span> <span class="token punctuation">)</span> <span class="token punctuation">;</span>
        <span class="token variable">$users</span> <span class="token operator">=</span> <span class="token variable">$this</span> <span class="token operator">-</span> <span class="token operator">&gt;</span> <span class="token property">userRepository</span> <span class="token operator">-</span> <span class="token operator">&gt;</span> <span class="token function">getAllAndSearch</span> <span class="token punctuation">(</span> <span class="token variable">$perPage</span> <span class="token punctuation">,</span> <span class="token variable">$searchParams</span> <span class="token punctuation">)</span> <span class="token punctuation">;</span>

        <span class="token keyword">return</span> <span class="token variable">$users</span> <span class="token punctuation">;</span>
    <span class="token punctuation">}</span>

/**

* api/users

* This api to call list user.

* param search name, email

* Example:

* http://localhost:8001/api/users?search%5Bname%5D=thinh&search%5Bemail%5D=nguyen

*/

public function index ( Request $request )

{

$searchParams = $request - > search ;

$perPage = config ( 'paginate.perPage' ) ;

$users = $this - > userRepository - > getAllAndSearch ( $perPage , $searchParams ) ;

return $users ;

}

The first line is the name of the API. Here is api / users
The following lines describe the param, response, message …

Result

After configuring and writing the API, we run the command:
$ php artisan apidoc:generate and then revisit http: // localhost: 8001 / docs / index.html to see the results:
Thank you everyone, have any comments on the article, please comment below.

Share the news now

Source : Viblo

Write API Document for project using Laravel

first . Introducing the package and installation

Setting

Configuration

Write the Document API

Result

TikTok becomes the second largest social platform in South Africa

The fastest depreciating after 9 months of launch, iPhone 14 Pro Max continues to break the bottom in Vietnam

Beginner's guide to R: Introduction

10 essential SublimeText plugins for JavaScript developers