README

🇷🇺 俄罗斯公民

我们，Laminas 的参与者，来自不同的国家。我们中许多人既有在俄罗斯的朋友、亲戚和同事，也有在乌克兰的。我们中的一些人出生在俄罗斯。我们中的一些人现在住在俄罗斯。我们中的一些人的祖父母在二战中与法西斯作战。在这里，没有人支持法西斯主义。

我们中的一员有一位乌克兰亲戚，她和儿子一起从家里逃了出来。由于前方路上发生轰炸，火车延误了。我们有朋友躲在防空洞里。在空袭之后，我们焦急地等待他们的消息，空袭不分青红皂白地袭击医院、学校、幼儿园和住宅。我们不是从任何媒体上得知这些的。这是我们亲眼目睹的。

您足够信任我们使用我们的程序，我们请求您再次信任我们。我们需要您的帮助。走出家门，抗议这场毫无意义的战争。停止杀戮。说“停止战争！”

🇺🇸 致俄罗斯公民

我们在 Laminas 的人来自世界各地。我们中许多人既在俄罗斯也有在乌克兰的朋友、家人和同事。我们中的一些人出生在俄罗斯。我们中的一些人现在住在俄罗斯。我们中的一些人的祖父母在二战中与纳粹作战。在这里，没有人支持法西斯主义。

我们的团队成员中有一位乌克兰亲戚，她和儿子一起逃离了家园。由于前方路上发生轰炸，火车延误了。我们有朋友躲在防空洞里。在空袭之后，我们焦急地等待他们的消息，空袭不分青红皂白地袭击医院、学校、幼儿园和住宅。我们不是从任何媒体上得知这些的。这是我们亲眼目睹的。

您足够信任我们使用我们的软件。我们要求您信任我们说出真相。我们需要您的帮助。走出家门，抗议这场毫无必要的战争。停止杀戮。说“停止战争！”

介绍

此 Laminas 模块可以与 Laminas API Tools 一起使用，以便

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

此模块通过提供连接到的端点（/api-tools/documentation[/:api[-v:version][/:service]]）来完成上述所有用例，使用内容协商提供 HTML 和 JSON 表示。

要求

请参阅 composer.json 文件。

安装

运行以下 composer 命令

$ composer require laminas-api-tools/api-tools-documentation

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

"require": {
    "laminas-api-tools/api-tools-documentation": "^1.2-dev"
}

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

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

return [
    /* ... */
    'modules' => [
        /* ... */
        'Laminas\ApiTools\Documentation',
    ],
    /* ... */
];

laminas-component-installer

如果您使用laminas-component-installer，该插件会为您安装api-tools-documentation作为模块。

配置

用户配置

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

系统配置

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

namespace Laminas\ApiTools\Documentation;

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

return [
    'router' => [
        'routes' => [
            'api-tools' => [
                '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,
        ],
    ],
    'api-tools-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',
        ],
    ],
];

Laminas事件

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

Laminas服务

视图助手

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

Laminas\ApiTools\Documentation\View\AgAcceptHeaders（又名agAcceptHeaders）用于创建HTML转义后的Accept头列表。
Laminas\ApiTools\Documentation\View\AgContentTypeHeaders（又名agContentTypeHeaders）用于创建HTML转义后的Content-Type头列表。
Laminas\ApiTools\Documentation\View\AgServicePath（又名agServicePath）用于创建服务路径的配置路由的HTML视图表示。
Laminas\ApiTools\Documentation\View\AgStatusCodes（又名agStatusCodes）用于创建状态码及其消息的转义列表。
Laminas\ApiTools\Documentation\View\AgTransformDescription（又名agTransformDescription）用于将书面描述转换为Markdown。

工厂

Laminas\ApiTools\Documentation\ApiFactory

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

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

laminas-api-tools / api-tools-documentation

维护者

详情