kleijnweb/php-api-routing-bundle

Symfony routing using php-api-descriptions

This project is no longer maintained

KleijnWeb\PhpApi\RoutingBundle

, _(*1)

, _(*2)

Install And Configure

Install using composer (composer require kleijnweb/php-api-routing-bundle)., _(*3)

Add OpenApi (or RAML) routing to your app, for example:, _(*4)

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

The type as well as the php-api prefix mentioned below is configurable:, _(*5)

api_routing:
  name: customname

Routing

To view the routes added by PhpApi\RoutingBundle, you can use Symfony's debug:router. Route keys include the API spec base filename to prevent collisions. For path parameters, PhpApiRoutingBundle adds additional requirements to the routes. This way /foo/{bar} and /foo/bar wont conflict when bar is defined to be an integer. This also supports Swaggers pattern and enum when dealing with string path parameters., _(*6)

Controller Resolution

All controllers must be defined as services in the DI container. PhpApi\RoutingBundle sees an operation id as composed from the following parts:, _(*7)

[router].[controller]:[method]

Router is a DI key namespace in this context. The router segment defaults to php-api.controller, but can be overwritten at the Path Object level using x-router:, _(*8)

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

The controller segments defaults to the resource name as extracted from the path by convention. For example, for path /foo/something the default router + controller would be: php-api.controller.foo., _(*9)

You can override the whole of [router].[controller] using x-router-controller. This will not only override the default, but any declaration of x-router, too:, _(*10)

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

The following is also supported (set controller for a specific method):, _(*11)

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

Finally, the method segment defaults to the HTTP method name, but may be overridden using Swagger's operationId or x-router-controller-method. Note the Swagger spec requires operationId to be unique, so while operationId can contain only the method name, you're usually better off using x-router-controller-method. You can also use a fully qualified operation id using double colon notation, eg "my.controller.namespace.myresource:methodName". Combining x-router or x-router-controller and a qualified operationId ignores the former., _(*12)

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
    ...

Contributing

Pull request are very welcome, as long as:, _(*13)

• All automated checks were successful
• Merge would not violate semantic versioning
• When applicable, the relevant documentation is updated

License

KleijnWeb\PhpApi\RoutingBundle is made available under the terms of the LGPL, version 3.0., _(*14)