README

帮助您从OpenAPI规范中创建REST API。

此包支持使用以下工具创建API的“设计优先”方法

• 将OpenAPI规范的路径项和操作加载为路由
• 验证对那些路由的请求
• 将验证后的JSON请求体反序列化为对象
• 为Symfony Serializer提供基于OpenAPI的序列化上下文
• 异常处理

安装

使用Symfony Flex的应用程序

打开命令行，进入您的项目目录并执行

composer require nijens/openapi-bundle

未使用Symfony Flex的应用程序

步骤1：下载包

打开命令行，进入您的项目目录并执行以下命令以下载此包的最新稳定版本

composer require nijens/openapi-bundle

此命令需要您已全局安装Composer，如Composer文档的安装章节中所述。

步骤2：启用包

然后，通过将其添加到项目src/Kernel.php文件中注册的包列表中来启用包

<?php
// src/Kernel.php

// ...
class Kernel extends BaseKernel
{
    public function registerBundles(): iterable
    {
        return [
            // ...
            new Nijens\OpenapiBundle\NijensOpenapiBundle(),
        ];
    }

    // ...
}

用法

在开始实现包之前，您应该花时间根据OpenAPI规范设计您的API。

以下资源可以帮助您设计规范

• OpenAPI规范版本3
• Swagger规范编辑器

路由

此包提供了一个路由加载器，可以加载来自您的OpenAPI文档的路径项和操作。

您通过在应用程序的路由中配置它来加载OpenAPI文档

# app/config/routes.yml

api:
    prefix: /api
    resource: ../openapi.yaml # or ../openapi.json
    type: openapi
    name_prefix: "api_"

在OpenAPI文档中，我们将使用x-openapi-bundle规范扩展来向文档中定义的操作添加额外的配置。

配置路由的控制器

通过在OpenAPI文档中的操作中添加controller属性到x-openapi-bundle规范扩展中来配置Symfony控制器。

paths:
  /pets/{uuid}:
    put:
      x-openapi-bundle:
        controller: 'Nijens\OpenapiBundle\Controller\PetController::put'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pet'
      responses:
        '200':
          description: 'Returns the stored pet.'

{
  "paths": {
    "/pets/{uuid}": {
      "put": {
        "x-openapi-bundle": {
          "controller": "Nijens\\OpenapiBundle\\Controller\\PetController::put"
        },
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Pet"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Returns the stored pet."
          }
        }
      }
    }
  }
}

controller属性的值与您通常添加到Symfony路由中的值相同。

使用操作的operationId作为Symfony路由的名称

在OpenAPI文档中，您可以给每个操作分配一个operationId，以便更好地识别它。要使用operationId作为加载的Symfony路由的名称，请添加以下包配置

# config/packages/nijens_openapi.yaml
nijens_openapi:
    routing:
        operation_id_as_route_name: true

使用operationId为您的路由提供更多的控制权，并允许您更好地使用它们与UrlGenerator一起。

请求验证

默认情况下，启用了已弃用的验证组件。要启用改进的验证组件，请添加以下YAML配置。

# config/packages/nijens_openapi.yaml
nijens_openapi:
    exception_handling:
        enabled: true

    validation:
        enabled: true

强烈建议同时启用改进的异常处理组件，因为它会将验证异常的详细信息转换为适当的JSON响应。

验证组件对以下请求部分进行验证：

• 内容类型：根据操作中requestBody属性配置的内容类型
• 查询参数：验证操作的配置查询参数和路径项。 注意，此类验证是实验性的，因为它可能缺少某些查询参数类型的验证。
• JSON请求体：根据操作中requestBody属性中的JSON模式

了解更多

• 激活查询参数请求验证
• 创建您自定义的请求验证器
• 内容类型验证解释（即将推出™）
• JSON请求体验证解释（即将推出™）
• 查询参数验证解释（即将推出™）

反序列化JSON请求体

将deserializationObject属性添加到操作的x-openapi-bundle规范扩展中可以激活请求体反序列化。

当请求体与您的OpenAPI文档中的JSON模式成功验证时，它将请求体反序列化为配置的反序列化对象。

反序列化对象根据以下方式注入到控制器中：

1. 控制器方法中参数的类型提示。

2. #[DeserializedObject]参数属性。（自PHP 8.0起支持）

   这是推荐的方法，因为它支持数组反序列化和混合参数类型的参数解析。

3. 可以添加到x-openapi-bundle规范扩展中的deserializationObjectArgumentName属性。

了解更多

• 如何使用单个控制器与Symfony Messenger组件

为Symfony Serializer提供基于OpenAPI的序列化上下文

⚠ 请注意：此功能仍然是实验性的。API可能会在未来小版本中更改。

SerializationContextBuilder帮助您为Symfony Serializer创建序列化上下文。它允许您根据OpenAPI规范轻松从对象或实体创建JSON响应。

以下示例展示了如何通过利用路由添加的请求属性来使用序列化上下文构建器。

<?php

use Nijens\OpenapiBundle\Routing\RouteContext;
use Nijens\OpenapiBundle\Serialization\SerializationContextBuilderInterface;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\Serializer\SerializerInterface;

class ExampleController
{
    public function __invoke(
        Request $request,
        SerializerInterface $serializer,
        SerializationContextBuilderInterface $serializationContextBuilder
    ): JsonResponse {
        $pet = new Pet();

        $serializationContext = $serializationContextBuilder->getContextForSchemaObject(
            'Pet',
            $request->attributes->get(RouteContext::REQUEST_ATTRIBUTE)[RouteContext::RESOURCE]
        );

        return JsonResponse::fromJsonString(
            $serializer->serialize($pet, 'json', $serializationContext)
        );
    }
}

异常处理

默认情况下，启用了之前的异常处理组件。要启用新的异常处理组件，请添加以下YAML配置。

# config/packages/nijens_openapi.yaml
nijens_openapi:
    exception_handling:
        enabled: true

新的异常处理组件使用问题详细信息JSON对象格式将异常（或Throwable）转换为清晰的错误响应。

如果您想实现自己的异常处理？将enabled更改为false。这将禁用组件的异常处理功能。

自定义异常的问题详细信息JSON对象响应

通过组件的异常处理配置，您可以修改任何Throwable的响应状态码和问题JSON响应体。有关更多信息，请参阅以下示例。

# config/packages/nijens_openapi.yaml
nijens_openapi:
    exception_handling:
        enabled: true
        exceptions:
            InvalidArgumentException:               # The fully qualified classname of the exception.
                status_code: 400                    # Modify the response status code of
                                                    # the exception response.

                type_uri: https://example.com/error # Add a unique type URI to the Problem Details.
                                                    # This could be a URL to additional documentation
                                                    # about the error.

                title: The request was invalid.     # Add a clear human-readable title property
                                                    # to the Problem Details.

                add_instance_uri: true              # Add the current route as instance_uri property
                                                    # to the Problem Details.

为了帮助您将问题详细信息JSON对象包含到您的OpenAPI文档中，我们提供了一个OpenAPI模板，其中包含此组件创建的特定问题详细信息JSON对象的模式。

致谢和认可

• 作者：Niels Nijens

另外，请参阅参与此项目的贡献者列表。

许可证

OpenAPI组件是在MIT许可证下授权的。请参阅LICENSE文件以获取详细信息。