README

从代码生成 Markdown 文档。

要求

• php >=7.2.5 || ~8.0.0

安装

$ composer require --dev osushi/apidoc

使用示例

脚本

1. 创建脚本文件

$ mkdir docs
$ touch apidoc.php

2. 编辑代码

<?php
require_once '../vendor/autoload.php';

use Osushi\Apidoc\Apidoc;
use Osushi\Apidoc\Permission;
use Osushi\Apidoc\Parameter;
use Osushi\Apidoc\Request;
use Osushi\Apidoc\Response;

Apidoc::init();
$apiDoc = Apidoc::getInstance();

$permission = new Permission();
$permission->add('users:*');
$permission->add('users:get');

$parameter = new Parameter();
$parameter->add('name', ['isa' => 'string', 'required' => true, 'comment' => 'user name', 'except' => ['bob', 'john']]);
$parameter->add('status', ['isa' => 'numric', 'default' => '10', 'comment' => 'user status', 'only' => ['10', '20', '30']]);
$parameter->note('Here is note1');
$parameter->note('Here is note2');

$apiDoc->record(
    'users:/users:GET', # This key format is {filename}:{path}:{method}
	$permission,
    $parameter,
    'Get All Users' # It's able to add comment
);

$request = new Request([
    'method' => 'GET',
    'path' => '/users',
    'parameters' => ['status' => 10, 'name' => 'tarou'],
    'headers' => ['Content-Type' => 'application/json'],
]);

$response = new Response([
    'code' => 200,
    'headers' => ['Content-Type' => 'application/json; charset=utf-8'],
    'body' => '{"id": 1,"name": "tarou","status": 10,"created_at": "2015-04-21T14:55:09.351Z","updated_at": "2015-04-21T14:55:09.351Z"}',
]);

$documents->example(
    'users:/users:GET',  # This key format is {filename}:{path}:{method}
    $request,
    $response,
    '200 Success' # It's able to add comment
);

$apiDoc->render();

3. 运行 apidoc

$ php apidoc.php APIDOC
$ tree docs
docs
├── toc.md
└── users.md

以下是示例

• toc.md
• users.md

⚠️ 如果你想渲染文档，请使用 APIDOC 参数运行脚本。

集成到 phpunit

1. 在 bootstrap.php 中初始化 apidoc

<?php
require_once '../vendor/autoload.php';

use Osushi\Apidoc\Apidoc;

Apidoc::init();

register_shutdown_function(function(){
   $apiDoc = Apidoc::getInstance();
   $apiDoc->render();
})

2. 编写你的功能测试。

<?php

use Tests\TestCase;
use Osushi\Apidoc\Apidoc;
use Osushi\Apidoc\Permission;
use Osushi\Apidoc\Parameter;
use Osushi\Apidoc\Request;
use Osushi\Apidoc\Response;

class UserIndexTest extends TestCase
{
    public static $apiDoc;

    public static function setUpBeforeClass()
    {
		# Set Permission Details
        $permission = new Permission();
        $permission->add('users:*');
        $permission->add('users:get');

        # Set Parameter Details
        $parameter = new Parameter();
        $parameter->add('name', ['isa' => 'string', 'required' => true, 'comment' => 'user name', 'except' => ['bob', 'john']]);
        $parameter->add('status', ['isa' => 'numric', 'default' => '10', 'comment' => 'user status', 'only' => ['10', '20', '30']]);
        $parameter->note('here is note');

        self::$apiDoc = Apidoc::getInstance();
        self::$apiDoc->record(
            'users:/users:GET', # This key format is {filename}:{path}:{method}
			$permission,
            $parameter,
            'Get All Users' # Be able to add comment
        );
    }

   public function testIndex()
   {
       $params = [
           'status' => 10,
           'name' => 'tarou',
       ];
       $response = $this->call('GET', '/users', $params);
       $response->assertStatus(200);

       $request = new Request([
           'method' => 'GET',
           'path' => '/users',
           'parameters' => $params,
           'headers' => ['Content-Type' => 'application/json'],
       ]);

       $response = new Response([
           'code' => $response->getStatusCode(),
           'headers' => $response->getHeaders(),
           'body' => (string) $response->getBody(),
       ]);

       self::$apiDoc->example(
           'users:/users:GET',  # This key format is {filename}:{path}:{method}
           $request,
           $response,
           '200 Success' # It's able to add comment
       );
   }
}

3. 运行 apidoc

$ APIDOC=1 phpunit
$ tree docs
docs
├── toc.md
└── users.md

文档

初始化

Apidoc::init($config);

配置

use Osushi\Apidoc\Config;

Apidoc::init([Parameter.php
  Config::OUTPUT_PATH => 'yourdir',
  Config::TOC => false,
]);

• Config::DOCUMENT_TEMPLATE_PATH - [String] 每个文档的 Twig 模板（默认：document.md）
• Config::DOCUMENT_TOC_TEMPLATE_PATH - [String] 文档目录的 Twig 模板（默认：document.toc.md）
• Config::DOCUMENT_TOC_TITLE - [String] 文档目录的标题（默认：# 目录）
• Config::TOC_TEMPLATE_PATH - [String] 目录的 Twig 模板（默认：toc.md）
• Config::TOC_TITLE - [String] 目录的标题（默认：# 目录）;
• Config::OUTPUT_PATH - [String] 输出文件的位置（默认：./docs）；
• Config::TOC - [Boolean] 是否生成 toc.md（默认：true）；

参数

use Osushi\Apidoc\Parameter;

$parameter = new Parameter();
$parameter->add('name', ['isa' => 'string', 'required' => true, 'comment' => 'user name', 'except' => ['bob', 'john']]);
$parameter->add('status', ['isa' => 'numric', 'default' => '10', 'comment' => 'user status', 'only' => ['10', '20', '30']]);
$parameter->note('here is note');

• add(string $value, array $options) - 为文档添加参数
  • options.isa - string (例如 string, integer)
  • options.required - boolean (例如 true/false)
  • options.comment - string (例如 comment)
  • options.format - string (例如 Ymd)
  • options.except - array (例如 ['bob', 'john'])
  • options.only - array (例如 [10, 20])
• note(string $node) - 为文档添加注释

请求

use Osushi\Apidoc\Request;

$request = new Request([
    'method' => {string method},
    'path' => {string path},
    'parameters' => {array params},
    'headers' => {array headers},
]);
# or
$request = new Request();
$request = setMethod({string method});
$request = setPath({string method});
$request = setParameters({array params});
$request = setHeaders({array headers});

响应

use Osushi\Apidoc\Response;

$response = new Response([
    'code' => {int status_code},
    'headers' => {array headers},
    'body' => {string json_body},
]);
# or
$response = new Response();
$response = setCode({int status_code});
$response = setHeaders({array headers});
$response = setBody({string json_body});

许可证

MIT