使用swagger文档在api平台的端点中询问其他GET参数

Question

我有一个symfony项目，在这里我使用api平台。我有一个实体，也有它的数据提供者。我在定义集合终结点的其他参数时遇到麻烦。

实体称为建议。它必须从弹性搜索返回文档集合。

端点是：

/suggestion

该端点侦听其他GET参数：

页面，级别

每次在请求端点时都会读取这两个参数。

在我的SuggestionsCollectionDataProvider.php课堂上，我有：

/**
     * Retrieves a collection.
     *
     * @param string $resourceClass
     * @param string|null $operationName
     * @return \Generator
     */
    public function getCollection(string $resourceClass, string $operationName = null): \Generator
    {
        $query = $this->requestStack->getCurrentRequest()->query;
        // I am reading these two parameters from RequestStack

        // this one is built-in
        $page = max($query->get('page', 1), 1); 

        // this is a custom one
        $level = $query->get('level', 0); 
        ...

在我的SuggestionRepository.php课上：

/**
     * @return \Generator
     */
    public function find(int $page, int $level): \Generator
    {
        // here I can process with $level without problems

Page参数是默认参数，它会大张旗鼓地生成集合。

API平台生成的Swagger文档的屏幕截图：

但是page参数现在是唯一可以在Web版本中编辑的参数。

我需要添加更多参数（level在这种情况下）来张扬并描述它们，因此用户/测试人员知道哪个参数实际上到达了此端点。

主要问题：

如何告诉api平台，我希望API的用户/测试人员（从客户端）输入其他一些参数，level例如？

我正在研究两天的所有文档，示例，但无法弄清楚：）

Answer 1

终于想通了。

我还没有找到文档，但是找到了一种方法。

在实体类中，Suggestion.php我添加了一些注释行：

namespace App\Entity;

use ApiPlatform\Core\Annotation\ApiProperty;
use ApiPlatform\Core\Annotation\ApiResource;
use Symfony\Component\Serializer\Annotation\Groups;
use Symfony\Component\Validator\Constraints as Assert;

/**
 * Class Suggestion. Represents an entity for an item from the suggestion result set.
 * @package App\Entity
 * @ApiResource(
 *     collectionOperations={
 *          "get"={
 *              "method"="GET",
 *              "swagger_context" = {
 *                  "parameters" = {
 *                      {
 *                          "name" = "level",
 *                          "in" = "query",
 *                          "description" = "Levels available in result",
 *                          "required" = "true",
 *                          "type" : "array",
 *                          "items" : {
 *                              "type" : "integer"
 *                          }
 *                      }
 *                  }
 *               }
 *          }
 *     },
 *     itemOperations={"get"}
 * )
 */

API平台中的结果视图包含DOC：

Answer 2

在 Api Platform 核心版本 2.4.6 中，向 get 注释添加“swagger_context”对我不起作用。相反，我使用了API Platform - Overriding the OpenAPI Specification 中提供的说明

就我而言，我不得不稍微偏离说明。在重写的 normalize 方法中，我必须先删除现有参数，然后将自定义定义添加到 $doc 参数数组中。正如 pedrouan 所做的那样，我能够添加 required=true 属性并且它以相同的方式工作。

在 services.yaml 我添加了：

    App\Swagger\SwaggerEventRequireDecorator:
         decorates: 'api_platform.swagger.normalizer.api_gateway'
         arguments: [ '@App\Swagger\SwaggerEventRequireDecorator.inner' ]
         autoconfigure: false

在 App\Swagger 文件夹中，我添加了以下类：

<?php

namespace App\Swagger;

use Symfony\Component\Serializer\Normalizer\NormalizerInterface;

final class SwaggerEventRequireDecorator implements NormalizerInterface
{
    private $decorated;

    public function __construct(NormalizerInterface $decorated)
    {
        $this->decorated = $decorated;
    }

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

        $customDefinition = [
            'name' => 'event',
            'description' => 'ID of the event the activities belong to.',
            'in' => 'query',
            'required' => 'true',
            'type' => 'integer'
        ];

//         e.g. remove an existing event parameter
        $docs['paths']['/scheduleamap-api/activities']['get']['parameters'] = array_values(array_filter($docs['paths']['/scheduleamap-api/activities']['get']['parameters'], function ($param) {
            return $param['name'] !== 'event';
        }));

    // e.g. add the new definition for event
    $docs['paths']['/scheduleamap-api/activities']['get']['parameters'][] = $customDefinition;

        // Remove other restricted parameters that will generate errors.
        $docs['paths']['/scheduleamap-api/activities']['get']['parameters'] = array_values(array_filter($docs['paths']['/scheduleamap-api/activities']['get']['parameters'], function ($param) {
            return $param['name'] !== 'event[]';
        }));

        return $docs;
    }

    public function supportsNormalization($data, $format = null)
    {
        return $this->decorated->supportsNormalization($data, $format);
    }
}

笔记：

1. 我还在 services.yaml 中将 autowire 和 autoconfig 设置为 true。

2. 我添加了一个自定义数据提供程序，以要求在对活动实体资源的所有 api 请求中设置事件属性过滤器。上面的自定义在做direct fetch或者url get请求的时候不需要设置。