Các developers thường viết ra một lượng lớn code bao gồm API và các thành phần khác trong các dự án trung bình cho đến lớn. Mặc dù có một quy ước về viết code, mỗi developer đều có một bình luận cá nhân và các tiêu chuẩn viết tài liệu. Một số thêm các ghi chú khó hiểu nhỏ trong khi những người khác đính kèm tài liệu Google Docs đầy đủ ghi lại method hoặc class một cách chi tiết. Vấn đề này trở nên rất nghiêm trọng khi số lượng end users ngày càng tăng lên và cần phải có tài liệu hướng dẫn thích hợp cho dự án. Trong trường hợp các API, đặc biệt là các REST APIs, một công cụ tạo ra REST API document trở nên cần thiết vì sự phân bố và sử dụng rộng rãi của API.

Bây giờ tôi sẽ bắt đầu ví dụ với một đoạn code:

namespace SearchElastic;
 
use SearchElastic\SearchAbstract\SearchAbstract;
 
/**
 
*  Class to perform basic search extends from SearchElastic\SearchAbstract\SearchAbstract
 
*/
 
class Search extends SearchAbstract
 
{
 
   /**
 
    * Search in Elasticsearch.
 
    *
 
    * @param  string  $query
 
    * @return Result from elasticsearch
 
    */
 
   public function search($query)
 
   {
 
       $this->validate($query);
 
       $client = $this->client->getClient();
 
       $result = array();
 
       // Change the match column name with the column name you want to search in it.
 
       $params = [
 
               'index' => $this->client->getIndex(),
 
               'type'  => $this->client->getType(),
 
               'body'  => [
 
                   'query' => [
 
                       'match' => [ $this->searchColumn => $query],
 
                   ],
 
               ],
 
           ];
 
       $query  = $client->search($params);
 
       return  $this->extractResult($query);
 
   }
 
}

Hãy chú ý về đoạn comment của đoạn code trên:

/**

    * Search in Elasticsearch.

    *

    * @param  string  $query

    * @return Result from elasticsearch

    */

Kiểu comment dài này được gọi là DocBlock, một comment nhiều dòng được khai báo ở trên cùng của việc thực hiện bất kỳ một class, interface, method, attributes và properties,... Những comment này thường nói với người đọc (developer hoặc end user) về hoạt động mà code thực hiện, parameter được yêu cầu, và dữ liệu được trả về. Bạn có thể thêm thông tin vào DocBlock.

Một DocBlock bắt đầu bằng một dấu gạch chéo và hai dấu hoa thị (/ **), nó giống như bắt đầu của một comment nhiều dòng nhưng thêm vào 1 dấu hoa thị nữa, và kết thúc bằng một dấu hoa thị và dấu gạch chéo phía trước (* /). Nó cũng chứa các thẻ, chú thích và mô tả để xác định namespaces và class insants.

Tạo Documentation cho API’s

DocBlocks rất quan trọng bởi vì chúng được sử dụng bởi một Symfony document generator package nổi tiếng được gọi là Sami. Rất phổ biến trong cộng đồng PHP, Sami cũng cung cấp khả năng tạo các mẫu custom twig templates và làm việc với các tài liệu phiên bản trên GitHub.

Trong bài này, tôi sẽ sử dụng dữ liệu Sami và một dự án trên GitHub Sync Mysql data with Elasticsearch để tự động tạo tài liệu.

Cài đặt Sami

SSH đến thư mục của dự án sau đó chạy command composer như sau:

composer require sami/sami

Sau khi cài đặt, bạn có thể kiểm tra xem Sami đã được cài đặt đúng cách và có đã sẵn sàng hoạt động hay không. Để làm điều này, hãy chạy lệnh sau:

$ php vendor/sami/sami/sami.php

Bạn sẽ nhận được output như sau:

Điều này cho thấy rằng Sami đã sẵn sàng để tạo ra document.

Clone GitHub App

Gần đây, tôi đã phát hiện ra một package tuyệt vời là Sync Mysql data to Elasticsearch có comments và Docblocks thích hợp.

Để bắt đầu, bạn nên clone package này vào ứng dụng của bạn, sử dụng command sau:

$ git clone https://github.com/ahmedkhan847/mysqlwithelasticsearch.git

Nếu bạn xem các files trong thư mục src của package này, bạn sẽ thấy các comment thích hợp được thêm vào tất cả các code blocks. Những block này giúp Sami hiểu structure và properties của các comonents trong package.

Tạo file config.php

Bạn cần phải tạo một file config.php trong thư mục config trong thư mục gốc. Sami đọc file này và tạo ra các file document cho phù hợp. Yêu cầu tối thiểu cho quá trình tạo document là đường dẫn thư mục mà code được lưu giữ.

Đây là những gì để bao gồm trong config.php:

<?php
 
return new Sami\Sami('mysqlwithelasticsearch/src/');

Bây giờ chúng ta chạy command sau:

$ php vendor/sami/sami/sami.php update config/config.php

Sami sẽ đọc tập tin cấu hình và tạo ra hai thư mục trong thư mục gốc của dự án, build (chứa các output files) và cache (chứa twig template cache).

Bây giờ hãy vào URL của build folder trên trình duyệt. URL sẽ có dạng: <link-web-site>/build/

Bạn sẽ thấy các output sau đây có chứa tất cả classes, namespaces, methods, properties và các variables được định nghĩa trong code:

Vì vậy, bằng cách sử dụng config cơ bản, tôi đã tạo ra toàn bộ tài liệu dự án (định dạng đúng) sử dụng Sami.

Bạn cũng có thể mở rộng file config.php bằng cách định nghĩa thêm các config như các trình lặp, các tùy chọn và các phiên bản cho tài liệu tương thích Git. Sami sử dụng thành phần Finder của Symfony với các mảng như một tham số.

Đây là một config nâng cao hơn:

use Sami\Sami;

use Sami\RemoteRepository\GitHubRemoteRepository;

use Symfony\Component\Finder\Finder;

$dir = __DIR__ . '/../mysqlwithelasticsearch/src';

$iterator = Finder::create()

   ->files()

   ->name('*.php')

   ->exclude('build')

   ->exclude('tests')

   ->in($dir);

$options = [

   'theme'                => 'default',

   'title'                => 'MYsql with Elasticsearch API Documentation',

   'build_dir'            => __DIR__ . '/../build',

   'cache_dir'            => __DIR__ . '/../cache',

];

$sami = new Sami\Sami($iterator, $options);

return $sami;

Tôi đã lưu source path trong $dir, và sau đó trong $iterator. Bao gồm tất cả các files PHP và loại trừ thư mục build và test (do đó chỉ bao gồm các files chứa code). Trong $options có chủ đề mặc định và tiêu đề cho tài liệu. Ngoài ra, nó chứa build_dir cho đầu ra và cache_dir cho twig caching.

Configure Git Versions

Khi làm việc với versions trong Git, bạn phải thêm tag ‘%version%’ . Để tạo documentation cho tất cả các tags trong version 2.0, các sub-branches của nó và master branch, bạn cần chỉ định add() và addFromTags()

<?php



use Sami\Sami;

use Sami\RemoteRepository\GitHubRemoteRepository;

use Sami\Version\GitVersionCollection;

use Symfony\Component\Finder\Finder;

$dir = __DIR__ . '/../mysqlwithelasticsearch/src';


$iterator = Finder::create()

   ->files()

   ->name('*.php')

   ->exclude('Resources')

   ->exclude('Tests')

   ->in($dir);


$versions = GitVersionCollection::create($dir)

   ->addFromTags('v2.0.*')

   ->add('2.0', '2.0 branch')

   ->add('master', 'master branch');

return new Sami($iterator, array(

   'theme'  => 'default',

   'versions'  => $versions,

   'title'  => 'MYsql with Elasticsearch API Documentation',

   'build_dir'  => __DIR__.'/../build/%version%',

   'cache_dir'  => __DIR__.'/../cache/%version%',

   'remote_repository' => new GitHubRemoteRepository(username/repository', '/path/to/repository’),

   'default_opened_level' => 2,

));

Now run the update command in the terminal:

$ php vendor/sami/sami/sami.php update config/config.php

Bây giờ bạn sẽ thấy thư mục build chứa các thư mục cho mỗi phiên bản.

Tạo Custom Themes (Các chủ đề tuỳ chỉnh)

Cho đến bây giờ, tôi đang sử dụng chủ đề mặc định. Tuy nhiên, Sami cung cấp sự linh hoạt để tạo ra chủ đề của riêng bạn.

Đối với điều này, bạn cần phải tạo một thư mục chủ đề trong thư mục gốc và xác định đường dẫn trong file config.php:

$templates = $sami['template_dirs'];

$templates[] = __DIR__ . '/../themes/';


$sami['template_dirs'] = $templates

Bây giờ để tạo một chủ đề mới, bạn cần thêm thư mục với tên của chủ đề. Mỗi chủ đề chứa một file manifest.yml, thường với nội dung sau:

name:   newtheme

parent: default

Chủ đề tùy chỉnh sẽ kế thừa các thuộc tính chủ đề mặc định.

Lời cuối

Sami làm giảm đáng kể quá trình tạo tài liệu cho API và các dự án PHP ở tất cả các quy mô. Với một config đơn giản, bạn đã hoàn thành nhiệm vụ thực sự mệt mỏi này.

Lưu ý rằng Sami không phải là công cụ tạo document hay REST API document duy nhất. Bạn cũng có thể thử phpDocumentor. Tuy nhiên, Sami cung cấp một số tùy chọn nâng cao mà không tìm thấy trong các lựa chọn khác.

Bài viết gốc: Generate Documentations For PHP Projects And REST API Through Sami