README

仓库废弃于 2019-12-31

此仓库已迁移至 laminas-api-tools/api-tools-documentation。

简介

此 Zend Framework 模块可以与 Apigility 结合使用，以

提供所有捕获文档信息的对象模型，包括
- 所有可用的 API。
- 每个 API 中可用的所有服务。
- 每个服务可用的所有操作。
- 每个可操作所需/预期的 Accept 和 Content-Type 请求头，以及预期响应头中的 Content-Type。
- 每个服务的配置字段。
提供可配置的 MVC 端点以返回文档。
- 默认情况下，文档将以 HTML 或序列化的 JSON 格式交付。
- 最终用户可以通过内容协商配置其他/额外格式。

该模块通过提供一个连接端点 (/apigility/documentation[/:api[-v:version][/:service]]) 来实现上述所有用例，使用内容协商提供 HTML 和 JSON 表示。

要求

请参阅 composer.json 文件。

安装

运行以下 composer 命令

$ composer require zfcampus/zf-apigility-documentation

或者，手动将以下内容添加到您的 composer.json 文件中的 require 部分

"require": {
    "zfcampus/zf-apigility-documentation": "^1.2-dev"
}

然后运行 composer update 确保已安装该模块。

最后，将模块名称添加到项目 config/application.config.php 文件下的 modules 键下

return [
    /* ... */
    'modules' => [
        /* ... */
        'ZF\Apigility\Documentation',
    ],
    /* ... */
];

zf-component-installer

如果您使用 zf-component-installer，该插件将为您安装 zf-apigility-documentation 作为模块。

配置

用户配置

此模块不使用任何用户配置。

系统配置

以下配置由模块定义，以确保在 Zend Framework 2 MVC 应用程序中运行。

namespace ZF\Apigility\Documentation;

use Zend\ServiceManager\Factory\InvokableFactory;
use Zend\View\Model\ViewModel;

return [
    'router' => [
        'routes' => [
            'zf-apigility' => [
                'child_routes' => [
                    'documentation' => [
                        'type' => 'segment',
                        'options' => [
                            'route'    => '/documentation[/:api[-v:version][/:service]]',
                            'constraints' => [
                                'api' => '[a-zA-Z][a-zA-Z0-9_.]+',
                            ],
                            'defaults' => [
                                'controller' => Controller::class,
                                'action'     => 'show',
                            ],
                        ],
                    ],
                ],
            ],
        ],
    ],
    'service_manager' => [
        'factories' => [
            ApiFactory::class => Factory\ApiFactoryFactory::class,
        ],
    ],
    'controllers' => [
        'factories' => [
            Controller::class => ControllerFactory::class,
        ],
    ],
    'zf-content-negotiation' => [
        'controllers' => [
            Controller::class => 'Documentation',
        ],
        'accept_whitelist' => [
            Controller::class => [
                0 => 'application/vnd.swagger+json',
                1 => 'application/json',
            ],
        ],
        'selectors' => [
            'Documentation' => [
                ViewModel::class => [
                    'text/html',
                    'application/xhtml+xml',
                ],
                JsonModel::class => [
                    'application/json',
                ],
            ],
        ],
    ],
    'view_helpers' => [
        'aliases' => [
            'agacceptheaders'         => View\AgAcceptHeaders::class,
            'agAcceptHeaders'         => View\AgAcceptHeaders::class,
            'agcontenttypeheaders'    => View\AgContentTypeHeaders::class,
            'agContentTypeHeaders'    => View\AgContentTypeHeaders::class,
            'agservicepath'           => View\AgServicePath::class,
            'agServicePath'           => View\AgServicePath::class,
            'agstatuscodes'           => View\AgStatusCodes::class,
            'agStatusCodes'           => View\AgStatusCodes::class,
            'agtransformdescription'  => View\AgTransformDescription::class,
            'agTransformDescription'  => View\AgTransformDescription::class,
        ],
        'factories' => [
            View\AgAcceptHeaders::class        => InvokableFactory::class,
            View\AgContentTypeHeaders::class   => InvokableFactory::class,
            View\AgServicePath::class          => InvokableFactory::class,
            View\AgStatusCodes::class          => InvokableFactory::class,
            View\AgTransformDescription::class => InvokableFactory::class,
        ],
    ],
    'view_manager' => [
        'template_path_stack' => [
            __DIR__ . '/../view',
        ],
    ],
];

ZF 事件

此模块没有事件或监听器。

ZF 服务

视图助手

以下视图助手列表有助于在视图脚本中呈现 API 文档模型。

ZF\Apigility\Documentation\View\AgAcceptHeaders（又称 agAcceptHeaders）用于生成一个 Accept 头列表，用于 HTML 的转义。
ZF\Apigility\Documentation\View\AgContentTypeHeaders（又名 agContentTypeHeaders）用于生成一个转义后的Content-Type头列表。
ZF\Apigility\Documentation\View\AgServicePath（又名 agServicePath）用于生成服务路径的HTML视图表示。
ZF\Apigility\Documentation\View\AgStatusCodes（又名 agStatusCodes）用于生成转义后的状态码及其消息列表。
ZF\Apigility\Documentation\View\AgTransformDescription（又名 agTransformDescription）用于将书面描述转换为Markdown格式。

工厂

ZF\Apigility\Documentation\ApiFactory

ApiFactory服务能够生成所需API文档的对象图表示。此对象图将由以下类型组成

ZF\Apigility\Documentation\Api：API的根节点。
ZF\Apigility\Documentation\Services：API中的服务数组（服务可以是REST或RPC风格的服务之一）。
ZF\Apigility\Documentation\Operations：服务中的操作数组。
ZF\Apigility\Documentation\Fields：服务中的字段数组。

zfcampus / zf-apigility-documentation

维护者

详细信息