PHPackages                             tobion/openapi-symfony-routing - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. tobion/openapi-symfony-routing

ActiveLibrary[API Development](/categories/api)

tobion/openapi-symfony-routing
==============================

Loads routes in Symfony based on OpenAPI/Swagger annotations

v1.2.1(4y ago)4219.5k↓50%5[1 issues](https://github.com/Tobion/OpenAPI-Symfony-Routing/issues)[1 PRs](https://github.com/Tobion/OpenAPI-Symfony-Routing/pulls)MITPHPPHP >=7.2CI failing

Since May 31Pushed 4y ago3 watchersCompare

[ Source](https://github.com/Tobion/OpenAPI-Symfony-Routing)[ Packagist](https://packagist.org/packages/tobion/openapi-symfony-routing)[ Docs](https://github.com/Tobion/OpenAPI-Symfony-Routing)[ RSS](/packages/tobion-openapi-symfony-routing/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (4)Dependencies (5)Versions (5)Used By (0)

OpenAPI-Symfony-Routing
=======================

[](#openapi-symfony-routing)

Loads routes in Symfony based on [OpenAPI/Swagger annotations](https://github.com/zircote/swagger-php).

[![CI](https://github.com/Tobion/OpenAPI-Symfony-Routing/workflows/CI/badge.svg)](https://github.com/Tobion/OpenAPI-Symfony-Routing/actions)

Installation
------------

[](#installation)

```
$ composer require tobion/openapi-symfony-routing

```

Version >= 1.2 requires zircote/swagger-php 3.x which is compatible with the OpenAPI Specification version 3. Version < 1.2 requires zircote/swagger-php 2.x which works with the OpenAPI Specification version 2 (fka Swagger). So tobion/openapi-symfony-routing can be used with both OpenAPI v2 and v3 and composer will select the compatible one for your dependencies. Route loading stays the same between those versions. You just need to update the annotations when migrating from OpenAPI v2 to v3.

Basic Usage
-----------

[](#basic-usage)

This library allows to (re-)use your OpenAPI documentation to configure the routing of your Symfony-based API. All the relevant routing information like the HTTP method, path and parameters are already part of the OpenAPI spec. This way you do not have to duplicate any routing information in Symfony. Consider having the controllers annotated with [zircote/swagger-php](https://github.com/zircote/swagger-php) like the following example:

```
use OpenApi\Annotations as OA;

/**
 * @OA\OpenApi(
 *     @OA\Info(title="My API", version="1.0")
 * )
 */
class MyController
{
    /**
     * @OA\Get(
     *     path="/foobar",
     *     @OA\Response(response="200", description="Success")
     * )
     */
    public function __invoke()
    {
    }
}
```

This library provides an `OpenApiRouteLoader` that you need to define as service and configure where to look for annotations like so:

```
# config/services.yaml
services:
    Tobion\OpenApiSymfonyRouting\OpenApiRouteLoader:
        autoconfigure: true
        # Looks for OpenAPI/Swagger annotations in the symfony flex default "src" directory
        factory: [Tobion\OpenApiSymfonyRouting\OpenApiRouteLoader, fromSrcDirectory]
```

Then you need to tell Symfony to load routes using it:

```
# config/routes.yaml
openapi_routes:
    resource: Tobion\OpenApiSymfonyRouting\OpenApiRouteLoader
    type: service
```

Advanced Features
-----------------

[](#advanced-features)

### Scanning annotations in different directories

[](#scanning-annotations-in-different-directories)

```
services:
    Tobion\OpenApiSymfonyRouting\OpenApiRouteLoader:
        autoconfigure: true
        factory: [Tobion\OpenApiSymfonyRouting\OpenApiRouteLoader, fromDirectories]
        arguments:
            - '%kernel.project_dir%/src'
            - '%kernel.project_dir%/vendor/acme/my-bundle/src'
```

### Naming routes

[](#naming-routes)

By default routes are auto-named based on the controller class and method. If you want to give routes an explicit name, you can do so using the OpenAPI `operationId` property:

```
use OpenApi\Annotations as OA;

class MyController
{
    /**
     * @OA\Get(
     *     path="/foobar",
     *     operationId="my-name",
     *     @OA\Response(response="200", description="Success")
     * )
     */
    public function __invoke()
    {
    }
}
```

### Add format suffix automatically

[](#add-format-suffix-automatically)

If your API supports different formats it is often common to optionally allow specifying the requested format as a suffix to the endpoint instead of having to always change headers for content negotiation. The routing loader allows to add a `.{_format}` placeholder automatically to the routes. This is disabled by default and can be enabled using a `format-suffix` OpenAPI vendor extension:

```
use OpenApi\Annotations as OA;

class MyController
{
    /**
     * @OA\Get(
     *     path="/foobar",
     *     x={"format-suffix": {
     *         "enabled": true,
     *         "pattern": "json|xml"
     *     }},
     *     @OA\Response(response="200", description="Success")
     * )
     */
    public function __invoke()
    {
    }
}
```

The above example will create a route `/foobar.{_format}` where the format is optional and can be json or xml. You can also enable the format-suffix globally by configuring it on the root OpenApi annotation and disable it for certain routes again, see [test fixtures](./tests/Fixtures/FormatSuffix/Controller.php).

### Order routes with priority

[](#order-routes-with-priority)

Since Symfony 5.1, the order of routes defined using annotations can be [influenced using a priority](https://symfony.com/doc/current/routing.html#priority-parameter). This can be used to make sure templated routes do not match before concrete routes without parameters for the same URL. The priority can also be set on OpenAPI annotations using a `priority` vendor extension:

```
use OpenApi\Annotations as OA;

class MyController
{
    /**
     * @OA\Get(
     *     path="/foobar",
     *     x={"priority": 10},
     *     @OA\Response(response="200", description="Success")
     * )
     */
    public function __invoke()
    {
    }
}
```

Contributing
------------

[](#contributing)

To run tests:

```
$ composer install
$ vendor/bin/simple-phpunit

```

###  Health Score

34

—

LowBetter than 77% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity37

Limited adoption so far

Community11

Small or concentrated contributor base

Maturity54

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~153 days

Total

4

Last Release

1719d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/d10b19f74fa2f712a4fbb9d9073c95d612c0f32e6ba95aed6f68e589c8e2688e?d=identicon)[Tobion](/maintainers/Tobion)

---

Top Contributors

[![Tobion](https://avatars.githubusercontent.com/u/610090?v=4)](https://github.com/Tobion "Tobion (31 commits)")

---

Tags

openapiroutingsymfonyroutesrouterswaggeropenapiannotationsroutingOAI

### Embed Badge

![Health badge](/badges/tobion-openapi-symfony-routing/health.svg)

```
[![Health](https://phpackages.com/badges/tobion-openapi-symfony-routing/health.svg)](https://phpackages.com/packages/tobion-openapi-symfony-routing)
```

###  Alternatives

[sylius/sylius

E-Commerce platform for PHP, based on Symfony framework.

8.4k5.6M651](/packages/sylius-sylius)[darkaonline/l5-swagger

OpenApi or Swagger integration to Laravel

2.9k34.0M112](/packages/darkaonline-l5-swagger)[darkaonline/swagger-lume

OpenApi or Swagger integration to Lumen

3372.3M3](/packages/darkaonline-swagger-lume)[harmbandstra/swagger-ui-bundle

Exposes swagger UI inside your Symfony project through a route (eg. /docs)

42867.3k](/packages/harmbandstra-swagger-ui-bundle)[erasys/openapi-php

Open API 3.0 builder and validation library for PHP that helps you write valid specs.

2080.3k5](/packages/erasys-openapi-php)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)