README

简介

zf-apigility-admin 模块提供了用于在 Apigility 中管理 API 的后端管理 API 和前端 Admin UI。

注意

不要在生产系统中启用此模块。

要求

请参阅 composer.json 文件。

安装

运行以下 composer 命令

$ composer require --dev "zfcampus/zf-apigility-admin"

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

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

return array(
    /* ... */
    'modules' => array(
        /* ... */
        'ZF\Apigility\Admin',
    ),
    /* ... */
);

通常，此模块应与 zf-development-mode 一起使用，以便在应用程序中条件性地启用该模块。这样做时，您将添加模块到项目的 config/development.config.php.dist 文件而不是 config/application.config.php 文件，并通过 php public/index.php development enable 启用它。

配置

此模块没有自定义用户级配置。

由于此特定模块负责提供 API 和 Apigility Admin UI，它需要大量的配置才能在开发环境中运行。由于开发者不太可能需要修改系统级配置，因此在此 README 中省略了它，但可以在存储库中找到。

路由

此模块公开可访问的 HTTP API 终端点和静态资源。

API 终端点

所有路由默认以 /apigility 前缀。

api/config

此端点是用于检查应用程序配置并提供对其中单个值的覆盖。所有覆盖都写入单个文件 config/autoload/development.php；您可以通过 zf-configuration.config-file 键在配置中覆盖该位置。

Accept: application/json, application/vnd.zfcampus.v1.config+json

application/json 将以平面数组的形式交付表示，键是点分隔的值，正如您在 INI 中找到的那样。

application/vnd.zfcampus.v1.config+json 将以树的形式交付配置。
Content-Type: application/json, application/vnd.zfcampus.v1.config+json

application/json 表示您正在发送键/值对，键是点分隔的值，正如您在 INI 文件中找到的那样。

application/vnd.zfcampus.v1.config+json 表示您正在发送嵌套数组/对象的配置。
方法：GET, PATCH
错误：application/problem+json

api/config/module?module={module name}

此操作与 api/config 端点完全相同，但期望一个已知的模块名称。当提供时，它允许您检查并操作该模块的配置文件。

api/authentication

此 REST 端点是用于创建、更新和删除应用程序的认证配置。它使用认证资源。

Accept: application/json

在成功时返回一个认证资源。
Content-Type: application/json

期望一个认证资源，其中包含创建新或更新现有 HTTP 认证所需的所有详细信息。
HTTP方法： GET、POST、PATCH、DELETE

GET在没有之前设置身份验证的情况下返回404响应。POST在成功时返回201响应。PATCH在成功时返回200响应。DELETE在成功时返回204响应。
错误：application/problem+json

api/authentication[/:authentication_adapter] (API V2)

此REST端点用于获取和更新用于Apigility的身份验证适配器。它使用身份验证资源版本2。

此端点仅适用于API 版本2。您需要在Appect头部传递以下mediatype

Accept: application/vnd.apigility.v2+json

Accept: application/json

成功时返回身份验证资源版本2。
内容类型： application/json

期望提供一个包含创建新身份验证或更新现有HTTP身份验证所需所有详细信息的身份验证资源版本2。
HTTP方法： GET、POST、PUT、DELETE

GET在没有之前设置身份验证适配器的情况下返回404响应。POST在成功时返回201响应。PUT在成功时返回200响应。DELETE在成功时返回204响应。

api/module/:name/authentication?version=:version (API V2)

此REST端点用于获取和更新特定API（模块）及其版本的身份验证映射，如果指定的话。

此端点仅适用于API 版本2。您需要在Appect头部传递以下mediatype

Accept: application/vnd.apigility.v2+json

Accept: application/json

成功时返回{ "authentication" : value }。
内容类型： application/json

期望一个包含包含身份验证适配器名称的authentication值的JSON。
HTTP方法： GET、PUT、DELETE

GET将返回一个{ "authentication" : value }响应。如果不存在身份验证适配器，则值将为false。

PATCH在成功时返回200响应，并附带更新的身份验证值。

DELETE在成功时返回204响应。

api/module/:name/authorization?version=:version

此REST端点用于获取和更新应用程序的授权配置。它使用授权资源。

Accept: application/json

成功时返回授权资源。
内容类型： application/json

期望一个包含指定授权规则的必要详细信息的授权资源。
HTTP方法： GET、PATCH

GET将始终返回一个实体；如果模块之前不存在配置，或者如果给定版本的任何给定服务未列在配置中，则将提供默认值。

PATCH在成功时返回200响应，并附带更新的实体。
错误：application/problem+json

api/db-adapter[/:adapter_name]

此REST端点用于创建、更新和删除命名的Zend\Db适配器；它使用db-adapter资源。

Accept: application/json

成功时返回一个db-adapter资源。
Content-Type: application/json

期望一个包含创建或更新数据库连接所需所有详细信息的db-adapter资源。
集合方法： GET、POST
资源方法： GET、PATCH、DELETE
错误：application/problem+json

api/module.enable

此端点将现有模块启用为Apigility。

Accept: application/json

成功时返回一个模块资源。
Content-Type: application/json

期望一个对象，其中包含描述现有ZF2模块的"module"属性。
方法：PUT
错误：application/problem+json

请求负载应该具有以下结构

{
    "module": "Status"
}

api/validators

此端点提供所有已注册验证器插件按顺序的列表；用例是为创建服务的输入过滤器时构建可用插件的下拉列表。任何在 ZF2 ValidatorPluginManager 服务中存在的验证器都将被表示。

Accept: application/json

成功时返回 application/json 响应。
方法：GET
错误：application/problem+json

成功请求的响应负载具有以下格式

{
  "validators": [
    "list",
    "of",
    "validators"
  ]
}

api/versioning

此端点用于向现有 API 添加新版本。如果未在负载中传递版本，则版本号将简单地递增。

Accept: application/json

成功时返回 JSON 结构，错误时返回 API-Problem 负载。
Content-Type: application/json

期望一个具有 "module" 属性的对象，提供 ZF2、Apigility 启用的模块名称；可选地，还可以提供一个 "version" 属性，以指示要使用的特定版本字符串。
方法：PATCH
错误：application/problem+json

请求负载应该具有以下结构

{
    "module": "Status",
    "version": 10
}

成功时，该服务返回以下结构

{
    "success": true,
    "version": "version string or integer"
}

api/module[/:name]

这是模块资源的标准端点。

Accept: application/json

成功时返回单个模块资源（当提供 name 时）或模块资源的集合（当未提供 name 时）。
Content-Type: application/json

期望一个具有描述要创建的模块的 "name" 属性的对象。
集合方法： GET、POST
资源方法：GET
错误：application/problem+json

当创建新的 API 模块时，使用以下请求负载

{
    "name": "Status"
}

api/module/:name/rpc[/:controller_service_name]

这是 RPC 资源的标准端点。

Accept: application/json

成功时返回单个 RPC 资源（当提供 controller_service_name 时）或 RPC 资源的集合（当未提供 controller_service_name 时）。
Content-Type: application/json

期望一个具有描述要创建的端点的 "service_name" 属性的对象。

您还可以提供 RPC 资源中列出的任何其他选项。
集合方法： GET、POST
资源方法：GET，PATCH
可以将查询字符串变量 version 传递到集合中，以按版本过滤结果：例如，/admin/api/module/:name/rpc?version=2。
错误：application/problem+json

必要的最小请求负载具有以下结构

{
    "service_name": "Status"
}

api/module/:name/rpc/:controller_service_name/inputfilter[/:input_filter_name]

此服务用于创建、更新和删除与给定 RPC 服务关联的命名输入过滤器。

Accept: application/json

成功时返回单个输入过滤器（当提供 input_filter_name 时）或输入过滤器的集合（当未提供 input_filter_name 时）。通常，只有一个输入过滤器将与给定的 RPC 服务相关联。

返回的输入过滤器还将组成一个属性 input_filter_name，它是给定输入过滤器的标识符。
Content-Type: application/json

期望一个输入过滤器。
集合方法： GET、POST
资源方法：GET，PUT，DELETE
错误：application/problem+json

api/module/:name/rest[/:controller_service_name]

这是 REST 资源的标准端点。

可用于任何类型的 REST 资源，包括 DB-Connected。

DB-Connected 资源期望以下附加属性（并将返回它们）

adapter_name：一个命名的 DB 适配器服务。
table_name：与此服务关联的数据库表。
hydrator_name：可选；用于填充数据库返回的行的 hydrator 服务的名称；默认为 ArraySerializable。
table_service：可选；默认情况下自动生成，但也可以提供其他TableGateway服务。
Accept: application/json

在成功时，返回单个REST资源（当提供了controller_service_name时）或REST资源集合（当未提供controller_service_name时）。
Content-Type: application/json

期望一个包含描述要创建的REST服务的resource_name属性的对象。

您还可以提供REST资源中列出的任何其他选项。
集合方法：GET、POST、DELETE
资源方法：GET，PATCH
可以将查询字符串变量version传递给集合，以按版本过滤结果：例如，/admin/api/module/:name/rest?version=2。
错误：application/problem+json

创建新的REST服务的最小结构如下

{
    "resource_name": "Status"
}

api/package

此端点是用于构建API部署包。

Accept: application/json

成功时返回 JSON 结构，错误时返回 API-Problem 负载。
Content-Type: application/json

期望一个包含“format”属性的的对象，用于文件格式ZIP、TAR、TGZ和ZPK；一个“apis”属性，其中包含要包含在包中的API列表；一个“composer”属性，指定是否执行composer，以及一个可选的“config”属性，包含要用于包中的应用程序配置文件夹的路径。
方法：GET、POST
错误：application/problem+json

POST的请求负载应具有以下结构

{
    "format": "the file format to be used for the package",
    "apis" : {
        "Test": true
    },
    "composer": true,
    "config": "the config path to be used in the package"
}

成功时，该服务返回以下结构

{
    "token": "a random token string",
    "format": "the file format used for the package"
}

此响应字段可用于GET方法中下载包文件。基本上，令牌是存储在系统临时文件夹中的临时文件名（在GNU/Linux中为/tmp）。

GET的请求负载应具有以下结构

GET /api/package?token=xxx&format=yyy

成功时，服务以application/octet-stream内容类型返回文件。

API模型

以下是一份列表，列出了通过上述API端点返回的各种模型或期望的请求体。

身份验证

HTTP基本身份验证

{
    "accept_schemes": [ "basic" ],
    "realm": "The HTTP authentication realm to use",
    "htpasswd": "path on filesystem to htpasswd file"
}

HTTP摘要身份验证

{
    "accept_schemes": [ "digest" ],
    "realm": "The HTTP authentication realm to use",
    "htdigest": "path on filesystem to htdigest file",
    "nonce_timeout": "integer; seconds",
    "digest_domains": "Space-separated list of URIs under authentication"
}

OAuth2身份验证

{
    "dsn": "PDO DSN of database containing OAuth2 schema",
    "username": "Username associated with DSN",
    "password": "Password associated with DSN",
    "route_match": "Literal route to match indicating where OAuth2 login/authorization exists"
}

身份验证2

HTTP基本身份验证

{
    "name" : "Name of the authentication adapter",
    "type": "basic",
    "realm": "The HTTP authentication realm to use",
    "htpasswd": "Path on filesystem to htpasswd file"
}

HTTP摘要身份验证

{
    "name" : "Name of the authentication adapter",
    "type": "digest",
    "realm": "The HTTP authentication realm to use",
    "digest_domains": "Space-separated list of URIs under authentication",
    "nonce_timeout": "integer; seconds",
    "htdigest": "Path on filesystem to htdigest file"
}

OAuth2身份验证（使用PDO）

{
    "name" : "Name of the authentication adapter",
    "type": "oauth2",
    "oauth2_type" : "pdo",
    "oauth2_route" : "Literal route to match indicating where OAuth2 login/authorization exists",
    "oauth2_dsn": "PDO DSN of database containing OAuth2 schema",
    "oauth2_username": "Username associated with DSN (optional)",
    "oauth2_password": "Password associated with DSN (optional)",
    "oauth2_options": "(optional)"
}

OAuth2身份验证（使用MongoDB）

{
    "name" : "Name of the authentication adapter",
    "type": "oauth2",
    "oauth2_type" : "mongo",
    "oauth2_route" : "Literal route to match indicating where OAuth2 login/authorization exists",
    "oauth2_dsn": "MongoDB DSN of database containing OAuth2 documents",
    "oauth2_database": "Database name",
    "oauth2_locator_name": "SomeServiceName class (optional)",
    "oauth2_options": "(optional)"
}

授权

{
    "Rest\Controller\Service\Name::__resource__": {
        "GET": bool,
        "POST": bool,
        "PUT": bool,
        "PATCH": bool,
        "DELETE": bool
    },
    "Rest\Controller\Service\Name::__collection__": {
        "GET": bool,
        "POST": bool,
        "PUT": bool,
        "PATCH": bool,
        "DELETE": bool
    },
    "Rpc\Controller\Service\Name::actionName": {
        "GET": bool,
        "POST": bool,
        "PUT": bool,
        "PATCH": bool,
        "DELETE": bool
    }
}

REST服务为其每个实体和集合实例都有一个条目。RPC服务为每个公开的操作名称有一个条目（这通常只有一个）。每个服务都有一个HTTP方法列表，带有标志。false值表示不需要授权；true值表示需要授权。

注意：如果将deny_by_default标志设置为应用程序中，则标志的含义相反；true表示方法是公开的，false表示需要认证。

数据库适配器

{
    "adapter_name": "Service name for the DB adapter",
    "database": "Name of the database",
    "driver": "Driver used to make the connection"
}

此外，还可以组合用于创建Zend\Db\Adapter\Adapter实例的任何其他属性：例如，“username”、“password”等。

输入过滤器

{
    "input_name": {
        "name": "name of the input; should match key of object",
        "validators": [
            {
                "name": "Name of validator service",
                "options": {
                    "key": "value pairs to specify behavior of validator"
                }
            }
        ]
    }
}

输入过滤器可以包含任意数量的输入，其格式遵循在[Zend Framework 2输入过滤器文档]中描述的Zend\InputFilter\Factory使用的格式（http://framework.zend.com/manual/2.3/en/modules/zend.input-filter.intro.html）。

目前，我们不允许嵌套输入过滤器。

模块

{
    "name": "normalized module name",
    "namespace": "PHP namespace of the module",
    "is_vendor": "boolean value indicating whether or not this is a vendor (3rd party) module",
    "versions": [
        "Array",
        "of",
        "available versions"
    ]
}

此外，module资源还组合了RPC和REST资源的关联关系；这些分别使用“rpc”和“rest”关系。

rpc

{
    "controller_service_name": "name of the controller service; this is the identifier, and required",
    "accept_whitelist": [
        "(Optional)",
        "List",
        "of",
        "whitelisted",
        "Accept",
        "mediatypes"
    ],
    "content_type_whitelist": [
        "(Optional)",
        "List",
        "of",
        "whitelisted",
        "Content-Type",
        "mediatypes"
    ],
    "http_options": [
        "(Required)",
        "List",
        "of",
        "allowed",
        "Request methods"
    ],
    "input_filter": "(Optional) Present in returned RPC services, when one or more input filters are present; see the inputfilter resource for details",
    "route_match": "(Required) String indicating Segment route to match",
    "route_name": "(Only in representation) Name of route associated with endpoint",
    "selector": "(Optional) Content-Negotiation selector to use; Json by default"
}

rest

{
    "controller_service_name": "name of the controller service; this is the identifier, and required",
    "accept_whitelist": [
        "(Optional)",
        "List",
        "of",
        "whitelisted",
        "Accept",
        "mediatypes"
    ],
    "adapter_name": "(Only in DB-Connected resources) Name of Zend\\DB adapter service used for this resource",
    "collection_class": "(Only in representation) Name of class representing collection",
    "collection_http_options": [
        "(Required)",
        "List",
        "of",
        "allowed",
        "Request methods",
        "on collections"
    ],
    "collection_query_whitelist": [
        "(Optional)",
        "List",
        "of",
        "whitelisted",
        "query string parameters",
        "to pass to resource for collections"
    ],
    "content_type_whitelist": [
        "(Optional)",
        "List",
        "of",
        "whitelisted",
        "Content-Type",
        "mediatypes"
    ],
    "entity_class": "(Only in representation) Name of class representing resource entity",
    "entity_identifier_name": "(Optional) Name of entity field representing the identifier; defaults to 'id'",
    "hydrator_name": "(Only in DB-Connected resources) Name of Zend\\Stdlib\\Hydrator service used for this resource",
    "route_identifier_name": "(Optional) Name of route parameter representing the resource identifier; defaults to resource_name + _id",
    "input_filter": "(Optional) Present in returned REST services, when one or more input filters are present; see the inputfilter resource for details",
    "module": "(Only in representation) Name of module in which resource resides",
    "page_size": "(Optional) Integer representing number of entities to return in a given page in a collection; defaults to 25",
    "page_size_param": "(Optional) Name of query string parameter used for pagination; defaults to 'page'",
    "resource_class": "(Only in representation) Name of class representing resource handling operations",
    "resource_http_options": [
        "(Required)",
        "List",
        "of",
        "allowed",
        "Request methods",
        "on individual resources"
    ],
    "route_match": "(Optional) String indicating Segment route to match; defaults to /resource_name[/:route_identifier_name]",
    "route_name": "(Only in representation) Name of route associated with api service",
    "selector": "(Optional) Content-Negotiation selector to use; HalJson by default",
    "table_name": "(Only in DB-Connected resources) Name of database table used for this resource",
    "table_service": "(Only in DB-Connected resources) Name of TableGateway service used for this resource"
}

ZF2事件

监听器

ZF\Apigility\Admin\Module

此监听器附加到MvcEvent::EVENT_RENDER，优先级为100。它负责根据控制器服务结果是否为实体或集合而条件性地附加监听器。如果检测到任一，则将监听器附加到ZF\Hal\Plugin\Hal事件的renderEntity和renderCollection.entity，确保它们将在HAL插件有机会开始渲染时被分发。

ZF2服务

模型

许多由 zf-apigility-admin 提供的模型服务，要么处理 PHP 代码的生成和修改，要么处理基于 PHP 的配置文件的生成和修改。

ZF\Apigility\Admin\Model\AuthenticationModel - 负责创建和修改 HTTP Basic、HTTP Digest 和 OAuth2 策略的特定认证配置。敏感信息将写入本地配置文件，而结构信息将写入全局和模块文件。
ZF\Apigility\Admin\Model\AuthorizationModelFactory - 负责将授权特定细节（允许/拒绝规则的 ACL 矩阵）写入模块配置文件。
ZF\Apigility\Admin\Model\ContentNegotiationModel - 负责将自定义内容协商选择器写入全局配置文件。
ZF\Apigility\Admin\Model\ContentNegotiationResource - 消费 ContentNegotiationModel 的 REST 资源，以暴露内容协商配置管理的 API 端点。
ZF\Apigility\Admin\Model\DbAdapterModel - 负责在应用级别的全局和本地配置文件之间写入数据库适配器特定配置。敏感信息将写入本地配置文件。
ZF\Apigility\Admin\Model\DbAdapterResource - 消费 DbAdapterModel 的 REST 资源，以在 Apigility API 中暴露数据库适配器配置管理的 API 端点。
ZF\Apigility\Admin\Model\DbConnectedRestServiceModel - 负责写入将数据库表公开为 REST 资源所需的所有配置信息。
ZF\Apigility\Admin\Model\DocumentationModel - 负责在模块配置目录中写入一个特殊命名的文件，该文件将包含所有请求、响应以及 API 其他可记录元素的 API 自定义文档。
ZF\Apigility\Admin\Model\InputFilterModel - 负责为每个模块编写输入过滤器规范配置。
ZF\Apigility\Admin\Model\FiltersModel - 负责通过 API 提供内置过滤器和它们的元数据列表。
ZF\Apigility\Admin\Model\HydratorsModel - 负责配置和管理全局 hydrator 服务名称列表。
ZF\Apigility\Admin\Model\ModuleModel - 负责聚合模块信息，包括 REST 和 RPC 服务，并通过 API 暴露这些信息。此外，在创建新模块时，这将创建 Apigility 启用的模块所需的代码工件。
ZF\Apigility\Admin\Model\ModuleResource - 负责将 ModuleModel 作为 Apigility API 中的 REST 资源公开。
ZF\Apigility\Admin\Model\RestServiceModel - 负责以可以在 Admin UI 中创建和修改的方式呈现 REST 服务，如 zf-rest 中定义的那样。
ZF\Apigility\Admin\Model\RestServiceResource - 负责消费 RestServiceModel 并将此模型作为 Apigility API 中的 REST 资源公开。
ZF\Apigility\Admin\Model\RestServiceModelFactory - 负责创建 RestServiceModel。
ZF\Apigility\Admin\Model\RpcServiceModel - 负责以可以在 Admin UI 中创建和修改的方式呈现 RPC 服务，如 zf-rpc 中定义的那样。
ZF\Apigility\Admin\Model\RpcServiceResource - 负责消费 RpcServiceModel 并将此模型作为 Apigility API 中的 REST 资源公开。
ZF\Apigility\Admin\Model\RpcServiceModelFactory - 负责创建 RpcServiceModel。
ZF\Apigility\Admin\Model\ValidatorsModel - 负责通过 API 提供可用的验证器列表。
ZF\Apigility\Admin\Model\ValidatorMetadataModel - 负责提供关于通过 ValidatorModel 和验证器 API 提供的验证器的元数据。
ZF\Apigility\Admin\Model\VersioningModel - 负责对工作流程和模块代码创建工件进行建模，这些工件是提供特定 Apigility 基础的 REST 或 RPC 服务的版本所需。
ZF\Apigility\Admin\Model\VersioningModelFactory - 负责创建 VersioningModel。

mardraze / zf-apigility-admin

维护者

详细信息

README

简介

注意

要求

安装

配置

路由

API 终端点

api/config

api/config/module?module={module name}

api/authentication

api/authentication[/:authentication_adapter] (API V2)

api/module/:name/authentication?version=:version (API V2)

api/module/:name/authorization?version=:version

api/db-adapter[/:adapter_name]

api/module.enable

api/validators

api/versioning

api/module[/:name]

api/module/:name/rpc[/:controller_service_name]

api/module/:name/rpc/:controller_service_name/inputfilter[/:input_filter_name]

api/module/:name/rest[/:controller_service_name]

api/package

API模型

身份验证

HTTP基本身份验证

HTTP摘要身份验证

OAuth2身份验证

身份验证2

HTTP基本身份验证

HTTP摘要身份验证

OAuth2身份验证（使用PDO）

OAuth2身份验证（使用MongoDB）

授权

数据库适配器

输入过滤器

模块

rpc

rest

ZF2事件

监听器

ZF\Apigility\Admin\Module

ZF2服务

模型