README

简介

此模块允许您快速创建 REST API 的文档。

我想要实现的主要功能

• 生成 REST API 文档。
  • [√] 描述可用参数的功能
  • [√] 创建多个重复的参数的一般描述
• 无限数量的文档化 API
  • [√] 为 ZF2 创建包含良好和标准化文档的模块
• 弹性且易于使用。
  • [√] 使用预定义的解释器进行配置或自行编写
  • [-] 您是否有自描述的 API 并希望自动从它构建文档？请帮助我编写这种解释器，或者等待我完成
• 文档齐全
  • [√] 模块附带由该模块文档化的 API 文档。
  • [√] 一些问题在技巧和窍门部分进行了描述
• 从文档页面测试和操作 API 的可能性
  • [√] 从文档执行 API 调用
  • [-] 执行授权（OAuth，BaseAuth，...）

阅读 TODO.md 以获取更多信息。

安装

1. cd my/project/directory
2. 创建一个包含以下内容的 composer.json 文件

{
    "require": {
        "widmogrod/zf2-rest-api-documentator": "1.*"
    }
}

1. 运行 php composer.phar install
2. 打开 my/project/folder/configs/application.config.php 并：- 将 'WidRestApiDocumentator' 添加到您的 'modules' 参数。- 将 'AsseticBundle' 添加到您的 'modules' 参数（如果需要包含 CSS，则为可选）

使用方法

以下是一个 PHP 配置文件，展示了如何在模块中实现简单的 REST API 文档。这是实现以下结果所需的最小配置。

<?php
return array(
    // Configuration namespace within this module looking for data
	'zf2-rest-api-documentator' => array(
	    // Contains collection of documentation descriptions.
        'docs' => array(
            // Namespace of module within REST API description resides. Must be unique per module.
            'my_module_name' => array(
                'name' => 'api.example.com',
                'version' => '1.1',
                'baseUrl' => 'http://127.0.0.1:8080/api',
                // Strategy is way, in which this configuration will be interpreted.
                'strategy' => 'standard',
                // General description for common thing in module, to skip redundancy
                'general' => array(
                    'params' => array(
                        'id' => array(
                            'type' => 'integer',
                            'required' => true,
                            'description' => 'Resource identificator'
                        ),
                        'limit' => array(
                            'type' => 'integer',
                            'description' => 'Limit API result to given value. Value must be between 1-100'
                        ),
                        'order' => array(
                            'type' => 'string',
                            'required' => false,
                            'description' => 'Retrieve API result ordered by given value. Acceptable values: asc, desc.'
                        ),
                    ),
                ),
                // REST API Endpoints, here you're describing your API
                'resources' => array(
                    'GET: /keywords' => 'Fetch list of keywords',
                    'POST: /keywords' => array(
                        'body' => array(
                            'type' => 'WidRestApiDocumentator\Body\JsonBody',
                            'params' => array(
                                'name' => array(
                                    'type' => 'string',
                                    'required' => true,
                                    'description' => 'Keyword name',
                                ),
                            ),
                        ),
                    ),
                    'GET: /keywords/<id>' => 'Fetch specific keyword',
                    'GET: /keywords/<id>/search_engines?limit=&order=',
                    'GET: /keywords/<id>/domains_positions_in_search_engine',
                    'PUT: /users/me' => array(
                        'description' => 'Demonstration endpoint that use headers & body params',
                        'headers' => array(
                            'X-Login' => array(
                                'type' => 'string',
                                'required' => true,
                                'description' => 'Header is test header. Nothing special.'
                            ),
                        ),
                        'body' => array(
                            'params' => array(
                                'token' => array(
                                    'type' => 'string',
                                    'description' => 'Authorization token',
                                ),
                            ),
                        ),
                    ),
                ),
            ),
        ),
	),
);

以下是一个示例，说明此配置将如何显示。

要查看此结果，请将浏览器中的应用程序地址输入到路由 /rest-api-docs。

技巧与窍门

设置您自己的文档路由。

<?php
return array(
    'router' => array(
        'routes' => array(
            'rest-api-docs' => array(
                'type' => 'Literal',
                'options' => array(
                    'route' => '/my-api-doc',
                    'defaults' => array(
                        'controller' => 'WidRestApiDocumentator\Controller\Docs',
                        'action' => 'show',
                        // NOTE: "my_module_name" is name of key in which your documentation was defined (see usage above)
                        'id' => 'my_module_name',
                        // NOTE: This param, will disable back to list button. Is optional. Defaut value is "1".
                        'show_back_link' => 0,
))))));

编写您自己的策略

当前模块有一个名为“standard”的策略。策略是解释文档配置的方式。这是一种非常有用的方式来创建您自己的解释器。为此，您需要做两件事：

1. 编写实现此接口的 WidRestApiDocumentator\StrategyInterface 的策略。
2. 告诉模块存在新的策略。创建此配置条目。

return array(
	'zf2-rest-api-documentator' => array(
        'strategies' => array(
            'invokables' => array(
                'myStrategy' => 'WidRestApiDocumentator\Strategy\Standard',
))));

如何在不安装 ZendSkeletonApplication 的情况下运行此模块

1. 克隆此模块 git@github.com:widmogrod/zf2-rest-api-documentator.git
2. 进入模块目录
3. 在此目录中运行 composer.phar install --dev
4. 在模块目录中创建文件 index.php 并包含以下内容

<?php
chdir(__DIR__);
if (!is_dir('public/assets')) {
    mkdir('public/assets', 0777, true);
}

$config = array(
    'modules' => array(
        'AsseticBundle',
        'WidRestApiDocumentator',
    ),
    'module_listener_options' => array(
        'config_glob_paths'    => array(
            'tests/config/autoload/{,*.}{global,local}.php',
        ),
        'config_static_paths' => array(
            'tests/config/autoload/assets.php',
            'config/api.config.php',
        ),
        'module_paths' => array(
            'WidRestApiDocumentator' => __DIR__
        ),
    ),
);

require_once 'vendor/autoload.php';

$app = Zend\Mvc\Application::init($config);
$app->run();

1. 在此目录中运行 Web 服务器，例如 php -S 127.0.0.1:8080

稳定性

在 master 分支上

在devel分支上