API 平台 - 自定义控制器/动作描述注释不起作用

Question

如果我在这里遗漏了一些东西，真的很抱歉，但是我已经搜索了问题和文档，但我找不到为什么这不起作用。也许我需要另一个关于使用互联网的教程；）

考虑以下实体注释，在 openapi_context 部分中，body.description 和 responses.200.description 根本没有任何效果，这让我有点发疯......你应该知道我正在使用 de/normalization 上下文但是这似乎不相关，所以我把它省略了。

/**
 * User entity
 *
 * @API\ApiResource(
 *  collectionOperations={
 *      "authenticate"={
 *          "method"="POST",
 *          "status"=200,
 *          "path"="/authenticate",
 *          "controller"=UserLoginController::class,
 *          "openapi_context"={
 *              "responses"={"200"={"description"="API token and secret"}},
 *              "body"={"description"="Login details"},
 *              "summary"="User authentication",
 *              "description"="Provides auth tokens on success",
 *          },
 *      },
 *  }
 * )
 *
 */
class User implements UserInterface
{
    ...
}

结果（蓝色块如预期，红色块不起作用）：

我在这个问题上花了太多时间，如果有人能帮我解决这个问题，我将不胜感激。我已经检查/尝试以下无济于事；

• Creating Custom Operations and Controllers
• Custom Symfony Action with API Platform bundle
• [Question] Documentation API with Swagger #143
• Changing Operations in the OpenAPI Documentation

作曲家版本（相关部分）：

{
    "require": {
        "php": ">=7.2.5",
        "api-platform/core": "^2.6",
        "symfony/framework-bundle": "5.2.*"
    }
}

Answer 1

经过一些实验，我发现openapi_context 注释属性确实似乎忽略了响应文档。但是，它确实允许您提供您缺少的请求正文描述：

#[ApiResource(
    collectionOperations: [
        'test' => [
            'method' => 'POST',
            'path' => '/test',
            'openapi_context' => [
                'summary' => 'The endpoint summary',
                'description' => 'The endpoint description',
                'requestBody' => [
                    'description' => 'The endpoint request body description', // This one
                    'content' => [
                        'application/json' => [
                            'schema' => [
                                '$ref' => '#/components/schemas/MyResource-some.group'
                            ],
                        ],
                    ],
                ],
            ],
        ]
    ],
)]

我在写这篇文章时使用的是 PHP 8.0.3 和 API Platform 2.6.3，不过将注释更改为 docblocks 应该会产生相同的结果。

然而，为了记录端点响应规范，我必须实现一个自定义 OpenApiFactoryInterface：

<?php declare(strict_types = 1);

namespace App;

use ApiPlatform\Core\OpenApi\Factory\OpenApiFactoryInterface;
use ApiPlatform\Core\OpenApi\Model\Operation;
use ApiPlatform\Core\OpenApi\Model\PathItem;
use ApiPlatform\Core\OpenApi\Model\RequestBody;
use ApiPlatform\Core\OpenApi\OpenApi;
use ArrayObject;
use UnexpectedValueException;

class MyResourceOpenApiFactory implements OpenApiFactoryInterface
{
    private OpenApiFactoryInterface $openApiFactory;

    public function __construct(OpenApiFactoryInterface $openApiFactory)
    {
        $this->openApiFactory = $openApiFactory;
    }

    public function __invoke(array $context = []): OpenApi
    {
        $openApi = ($this->openApiFactory)($context);
        $components = $openApi->getComponents();
        $schemas = $components->getSchemas();
        if (null === $schemas) {
            throw new UnexpectedValueException('Failed to obtain OpenApi schemas');
        }

        $pathItem = new PathItem(
            'MyResource test endpoint',
            'A test summary',
            'A test description',
            null,
            null,
            // Your custom post operation
            new Operation(
                'testMyResourceCollection', // the operation route name
                [
                    'MyResource' // your resource name
                ],
                [
                    // response specifications
                    '201' => [
                        'description' => 'test endpoint 201 response description',
                        'content' => [
                            'application/json' => [
                                'schema' => [
                                    '$ref' => '#/components/schemas/MyResource-read', // your resource (read) schema
                                ],
                            ],
                        ],
                    ],
                ],
                'A test endpoint summary',
                'A test endpoint description',
                null,
                [],
                new RequestBody(
                    'A test request body description',
                    new ArrayObject([
                        'application/json' => [
                            'schema' => [
                                '$ref' => '#/components/schemas/MyResource-write', // your resource (write) schema
                            ],
                        ],
                    ]),
                ),
            ),
        );

        $paths = $openApi->getPaths();
        $paths->addPath('/my_resources/test', $pathItem);
        return $openApi;
    }
}

让这个OpenApiFactoryInterface 实现由服务容器作为装饰器连接到api_platform.openapi.factory：

App\MyResourceOpenApiFactory:
    decorates: 'api_platform.openapi.factory'
    autoconfigure: false

将对示例 MyResource 名称的引用更改为您选择的资源名称（如 User）。

旁注： 在我看来，在 API 平台中自定义 OpenApi 端点文档的整个过程目前相当复杂。使用我提供的实现作为您自己实现的参考，因为您很可能需要对其进行一些调整才能使其满足您的特定用例。