README

根据 OpenAPI/Swagger 注释在 Symfony 中加载路由。

安装

$ composer require tobion/openapi-symfony-routing

版本 >= 1.2 需要 zircote/swagger-php 3.x，该版本与 OpenAPI 规范 3 兼容。版本 < 1.2 需要 zircote/swagger-php 2.x，该版本与 OpenAPI 规范 2（即 Swagger）兼容。因此，tobion/openapi-symfony-routing 可以与 OpenAPI v2 和 v3 一起使用，Composer 将为您选择兼容的版本。不同版本之间的路由加载保持不变。您只需要在从 OpenAPI v2 迁移到 v3 时更新注释。

基本用法

此库允许您（重新）使用您的 OpenAPI 文档来配置基于 Symfony 的 API 的路由。所有相关的路由信息，如 HTTP 方法、路径和参数，都已经包含在 OpenAPI 规范中。这样，您就不需要在 Symfony 中重复任何路由信息。考虑使用以下示例将控制器注释为 zircote/swagger-php

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()
    {
    }
}

此库提供了一个 OpenApiRouteLoader，您需要将其定义为服务并配置查找注释的位置，如下所示

# 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]

然后您需要告诉 Symfony 使用它来加载路由

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

高级功能

在不同的目录中扫描注释

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

命名路由

默认情况下，路由会根据控制器类和方法自动命名。如果您想给路由一个显式的名称，可以使用 OpenAPI 的 operationId 属性来实现

use OpenApi\Annotations as OA;

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

自动添加格式后缀

如果您的 API 支持不同的格式，通常允许在端点后指定请求的格式作为后缀，而不是始终更改内容协商的头部。路由加载器允许自动将 .{_format} 占位符添加到路由中。默认情况下，这是禁用的，可以使用 format-suffix OpenAPI 扩展启用它

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()
    {
    }
}

上述示例将创建一个路由 /foobar.{_format}，其中格式是可选的，可以是 json 或 xml。您还可以通过在根 OpenApi 注释中配置它来全局启用格式后缀，并再次禁用某些路由，请参阅测试固定装置。

按优先级排序路由

由于 Symfony 5.1 的推出，使用注释定义的路由的顺序可以通过优先级来影响。这可以确保模板路由在未提供参数的同一 URL 上的具体路由之前不会匹配。优先级也可以通过 priority 扩展设置在 OpenAPI 注释中

use OpenApi\Annotations as OA;

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

贡献

运行测试

$ composer install
$ vendor/bin/simple-phpunit

tobion / openapi-symfony-routing

维护者

详情