README

安装与配置

使用 composer 安装（composer require kleijnweb/php-api-routing-bundle）。

将 OpenApi（或 RAML）路由添加到您的应用中，例如

test:
  resource: "path/to/spec.yml"
  type: php-api

以下提到的 type 以及 php-api 前缀是可配置的

api_routing:
  name: customname

路由

要查看 PhpApi\RoutingBundle 添加的路由，可以使用 Symfony 的 debug:router。路由键包括 API 规范的基本文件名以防止冲突。对于路径参数，PhpApiRoutingBundle 向路由添加额外的要求。这样，当 bar 被定义为整数时，/foo/{bar} 和 /foo/bar 不会冲突。这也支持 Swaggers 的 pattern 和 enum，当处理字符串路径参数时。

控制器解析

所有控制器都必须在 DI 容器中定义为服务。PhpApi RoutingBundle 将 operation id 视为由以下部分组成

[router].[controller]:[method]

在此上下文中，Router 是 DI 密钥命名空间。默认情况下，router 段默认为 php-api.controller，但可以在 Path Object 级别使用 x-router 覆盖。

paths:
  x-router: my.default.controller.di.namespace
  /foo:
    ...
  /foo/{bar}:
    ...

默认情况下，controller 段默认为从路径中通过约定提取的资源名称。例如，对于路径 /foo/something，默认路由 + 控制器将是：php-api.controller.foo。

您可以使用 x-router-controller 覆盖整个 [router].[controller]。这将不仅覆盖默认值，还会覆盖任何 x-router 的声明。

paths:
  x-router: my.default.controller.di.namespace
  /foo:
    ...
  /foo/{bar}:
    x-router-controller: an.alternate.di.namespace.controller
    ...

以下也是支持的（为特定方法设置控制器）

paths:
  x-router: my.default.controller.di.namespace
  /foo:
    ...
  /foo/{bar}:
    patch:
      x-router-controller: an.alternate.di.namespace.controller
    ...

最后，method 段默认为 HTTP 方法名称，但可以使用 Swagger 的 operationId 或 x-router-controller-method 覆盖。请注意，Swagger 规范要求 operationId 唯一，因此虽然 operationId 可以仅包含方法名称，但通常更好的做法是使用 x-router-controller-method。您还可以使用完全限定的操作 ID，例如 "my.controller.namespace.myresource:methodName"。使用 x-router 或 x-router-controller 和合格的操作 ID 会忽略前者。

paths:
  x-router: my.default.controller.di.namespace
  /foo:
    ...
  /foo/{bar}:
    x-router-controller: an.alternate.di.namespace.controller
    post:
      # Ingores declarations above
      operationId: my.controller.namespace.myresource:methodName
    ...

paths:
  x-router: my.default.controller.di.namespace
  /foo:
    ...
  /foo/{bar}:
    post:
      # Resolves to 'my.default.controller.di.namespace.foo:methodName'
      x-router-controller-method: methodName
    ...

paths:
  /foo:
    ...
  /foo/{bar}:
    x-router-controller: an.alternate.di.namespace.controller
    post:
      # Same as above. Valid, but discouraged
      operationId: methodName
    ...

贡献

只要符合以下条件，Pull request 非常欢迎：

• 所有自动化检查都成功执行
• 合并不会违反语义版本控制
• 适用时，更新相关文档

许可证

KleijnWeb\PhpApi\RoutingBundle 在 LGPL，版本 3.0 的条款下提供。