在 API 平台注释中使用参数

Question

我正在研究如何将动态变量添加到 API 平台 @ApiProperty 注释中。我发现 Symfony 允许这样做，但它似乎在 API 平台注释中不起作用。例如：

/**
 * Redirection URL.
 *
 * @Groups({"authorization_code_login_write", "authorization_code_logout_write"})
 * @ApiProperty(
 *     attributes={
 *         "openapi_context"={
 *             "type"="string",
 *             "example"="%app.auth.default.redirect%"
 *         }
 *     }
 * )
 */
protected ?string $redirectionUrl = null;

%app.auth.default.redirect%未被同名容器参数替换。我该怎么办？

Answer 1

乍一看，我只看到一种方法 - 在 openapi_context 中创建您自己的属性，比方说 my_redirect_example。

像这样，例如：

"openapi_context"={
    "type"="string",
    "my_redirect_example"=true
}

然后需要装修like in documentation

嗯，像这样：

public function normalize($object, $format = null, array $context = [])
{
    $docs = $this->decorated->normalize($object, $format, $context);


    $redirectUrl = .... # your own logic to get this dynamical value

    foreach ($docs['paths'] as $pathName => $path) {
        foreach ($path as $operationName => $operation) {
            if ($operation['my_redirect_example'] ?? false) {
                $docs['paths'][$pathName][$operationName]['example'] = $redirectUrl;
            }
        }
    }

    return $docs;
}

应该可以。无论如何 - 这只是一个例子（我没有测试它），只是为了了解你如何处理它。

当然，您可以将 true 值替换为您自己的值，并在 if 语句中使用它来获取它，具体取决于您自己的逻辑。

Answer 2

方法是按照文档装饰 Swagger Open API 生成器服务 (https://api-platform.com/docs/core/swagger/#overriding-the-openapi-specification)。

添加您自己的服务：

# api/config/services.yaml
services:
    'App\Swagger\SwaggerDecorator':
        decorates: 'api_platform.swagger.normalizer.api_gateway'
        arguments: [ '@App\Swagger\SwaggerDecorator.inner' ]
        autoconfigure: false

然后创建服务 class :

<?php

namespace App\Swagger;

use Symfony\Component\Serializer\Normalizer\NormalizerInterface;

/**
 * Custom Swagger decorator to remove/edit some API documentation information.
 */
final class SwaggerDecorator implements NormalizerInterface
{

    /**
     * Decorated base Swagger normalizer.
     *
     * @var NormalizerInterface
     */
    protected NormalizerInterface $decorated;

    /**
     * SwaggerDecorator constructor.
     *
     * @param NormalizerInterface $decorated
     */
    public function __construct(NormalizerInterface $decorated)
    {
        $this->decorated = $decorated;
    }

    /**
     * {@inheritDoc}
     */
    public function normalize($object, string $format = null, array $context = [])
    {
        $docs = $this->decorated->normalize($object, $format, $context);
        $docs['components']['schemas']['authorization-authorization_code_login_write']['properties']['redirectionUrl']['example'] = 'https://example.com/my-dynamic-redirection';
        $docs['components']['schemas']['authorization:jsonld-authorization_code_login_write']['properties']['redirectionUrl']['example'] = 'https://example.com/my-dynamic-redirection';

        return $docs;
    }

    /**
     * {@inheritDoc}
     */
    public function supportsNormalization($data, string $format = null)
    {
        return $this->decorated->supportsNormalization($data, $format);
    }
}

您只需找到要使用的键，浏览模式可以帮助您的 Swagger UI。在我的示例中，authorization 是我的 API 资源实体的简称，authorization_code_login_write 是操作的非规范化上下文值。

给你：

当然，理想的解决方案将遍历所有模式并将找到的配置参数替换为它们的真实值。也许这个功能可以在 API 平台本身完成（关注问题：https://github.com/api-platform/api-platform/issues/1711）

在 API 平台注释中使用参数

Use parameter in API platform annotation

php

annotations

symfony

api-platform.com