README

使用纯PHP生成API文档。

安装

composer require mvaliolahi/sibdoc

1. 实例化 SibDoc。

要为您的出色API生成文档，请创建一个SibDoc实例

$api =  new SibDoc([
    'url'         => 'http://127.0.0.1:8000',
    'title'       => 'Our Awesome API',
    'description' => 'Generate API Document Using Lovely PHP.',
]);

提示：还有一个可选参数叫做 'background_color => '#0099cc'，可以用来指定文档的背景颜色。

2. 定义端点

   
$api->post('transactions/{id}', function (Request $request) {

    //  Define Request.
    $request->title('Show transaction.');
    $request->version("v1"); // Optional

    $request->parameters([
        'token' => 'required',
        'transaction_id' => 'required',
    ]);

    // Define Response.
    $success = (new Response())
        ->title('Success')
        ->code(200)
        ->body([
            'id'         => 'numeric',
            'status'     => 'PAID | UNPAID',
            'created_at' =>  'timestamp', 
        ]);        
        
    // Assings Reaponses to the Request.
    $request->response($success);
    
});

技巧

请求可以有多个响应，只需定义另一个响应对象并将其分配给 $request。
$request->response('Success', $success); 是将响应分配给请求并定义响应别名的另一种方法。
请求和响应都具有 description() 方法，此方法为可选。
您可以使用 headers() 方法为请求和响应对象定义头，例如

$request->headers([]).

或定义一个通用头，例如使用 $api->requestHeaders([]) 或 $api->responseHeaders([]) 方法。

可用方法

get
post
put
patch
delete
head
connect
options
trace

定义组

      
$api->group('app', function(SibDoc $api) {
    
    $api->delete('posts/{id}', function (Request $request) {
        // Define request and response.
    });
        
});

定义模型

$api->model('user', [
    'id'     => 'numeric',
    'name'   => 'string',
    'family' => 'string',
    'avatar' => 'url',
]);

将模型用作响应体的部分

$api->get('users', function (Request $request) {

    $request->title('Get all users');
    $request->version(1.2);
    $request->description('...');
    $request->parameters(['token' => 'required']);
    
    $success = (new Response())
        ->title('Success')
        ->description('...')
        ->code(200)
        ->body([
            'data'  => [ $api->model('user') ] // when second argument is null it will act as getter.
        ]);    
        
    $fail = (new Response())
        ->title('Fail')
        ->description('...')
        ->code(404)
        ->body([
            'data'  => []
        ]); 
        
    $request->response($success);    
    $request->response($fail);    
                   
});

3. 生成Html

默认情况下，SibDoc可以为您生成一个名为 document.html 的文件。

$api->saveTo('/home/meysam/');

技巧

第一个参数指定导出路径，调用 saveTo() 方法并传递相关参数后，将在该路径下生成一个名为 document.html 的文件。
第二个参数指向用于创建html文件的内置生成器。
您可以定义自定义生成器来创建所需的格式，例如 markdown 或可能是一个 json 文件。我将在下面为您演示！

创建自定义生成器

首先，您需要一个常规类，并且应该从 DocumentGenerator 抽象类扩展它。

/**
 * Class FakeGenerator
 * @package Tests\Generators
 */
class FakeGenerator extends DocumentGenerator
{
    /**
     * @param $path
     * @return mixed
     */
    public function format($path)
    {
        return 'fake generator!';
    }
}

在扩展您的类之后，您可以使用几种方法来生成自定义格式。

groups()
- 为您提供所有定义的组。当组名不是字符串时，这意味着它不是一个组，而是一个单个端点。
endpoints()
- 为您提供包含所有端点和组的数组，每个组可以有多个端点。
models()
backgroundColor()
- 为您提供您在SibDoc实例参数中传递的 background_color 值。

如何使用它们以及您的最终格式取决于您。

最后，您应将生成器作为参数传递给SibDoc

$api = new SibDoc([
    'url'         => 'http://127.0.0.1:8000',
    'title'       => 'SibDoc Document Generator',
    'description' => 'Generate Api Document Using Pure PHP.',
    'generator'   => [
        'fake_generator' => FakeGenerator::class
    ],
]);

// define you groups and endpoints

$api->saveTo('/home/user/', 'fake_generator');

mvaliolahi/ sibdoc

维护者

详细信息