README

仓库已废弃 2019-12-31

此仓库已迁移到 laminas-api-tools/api-tools-documentation-swagger.

简介

本模块为 Apigility 提供了通过 Swagger UI 显示 API 文档的功能。

在 URI 路径 /apigility/swagger 启用此模块后，Swagger UI 即可立即访问。

除了提供 HTML UI，此模块还插入到主 Apigility 文档资源（路径为 /apigility/documentation）中，以便允许以 application/vnd.swagger+json 媒体类型返回文档负载；此资源为 Swagger UI 提供数据。您可以通过将媒体类型 application/vnd.swagger+json 作为 Accept 报头通过路径 /apigility/documentation/:module/:service 传递来访问此表示。

要求

请参阅 composer.json 文件。

安装

运行以下 composer 命令

$ composer require zfcampus/zf-apigility-documentation-swagger

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

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

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

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

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

zf-component-installer

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

路由

/apigility/swagger

显示 Swagger UI JavaScript 应用程序。

资产: /zf-apigility-documentation-swagger/

用于提供 Swagger UI 客户端应用程序的各种 CSS、图像和 JavaScript 库。

配置

系统配置

以下内容是确保模块在 ZF2 和/或 Apigility 启用的应用程序中正常工作的必要条件

namespace ZF\Apigility\Documentation\Swagger;

return [
    'router' => [
        'routes' => [
            'zf-apigility' => [
                'child_routes' => [
                    'swagger' => [
                        'type' => 'segment',
                        'options' => [
                            'route'    => '/swagger',
                            'defaults' => [
                                'controller' => SwaggerUi::class,
                                'action'     => 'list',
                            ],
                        ],
                        'may_terminate' => true,
                        'child_routes' => [
                            'api' => [
                                'type' => 'segment',
                                'options' => [
                                    'route' => '/:api',
                                    'defaults' => [
                                        'action' => 'show',
                                    ],
                                ],
                                'may_terminate' => true,
                            ],
                        ],
                    ],
                ],
            ],
        ],
    ],

    'service_manager' => [
        'factories' => [
            SwaggerViewStrategy::class => SwaggerViewStrategyFactory::class,
        ],
    ],

    'controllers' => [
        'factories' => [
            SwaggerUi::class => SwaggerUiControllerFactory::class,
        ],
    ],

    'view_manager' => [
        'template_path_stack' => [
            'zf-apigility-documentation-swagger' => __DIR__ . '/../view',
        ],
    ],

    'asset_manager' => [
        'resolver_configs' => [
            'paths' => [
                __DIR__ . '/../asset',
            ],
        ],
    ],

    'zf-content-negotiation' => [
        'accept_whitelist' => [
            'ZF\Apigility\Documentation\Controller' => [
                0 => 'application/vnd.swagger+json',
            ],
        ],
        'selectors' => [
            'Documentation' => [
                ViewModel::class => [
                    'application/vnd.swagger+json',
                ],
            ],
        ],
    ],
];

ZF 事件

监听器

ZF\Apigility\Documentation\Swagger\Module

该监听器附加到 MvcEvent::EVENT_RENDER 事件，优先级为 100。它的目的是在控制器响应为 ZF\Apigility\Documentation\Swagger\ViewModel 视图模型的情况下（可能是基于 Accept 媒体类型选择的内容协商视图模型），有条件地附加一个视图策略到视图系统中。

ZF 服务

视图模型

ZF\Apigility\Documentation\Swagger\ViewModel

此视图模型负责将可用的 ZF\Apigility\Documentation 模型转换为 Swagger 特定模型，并将它们进一步转换为数组，以便稍后作为 JSON 进行渲染。