Php 如何使用swagger文档在api平台的端点中请求其他GET参数？

我有一个symfony项目，在那里我使用api平台

我有一个实体，我有它的数据提供者。我在为集合终结点定义附加参数时遇到麻烦

一个实体叫做建议。它必须从弹性搜索返回文档集合

端点是：

/suggestion

此端点侦听其他GET参数：

页面，级别

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

在我的

suggestionCollectionDataProvider.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); 
        ...

在my

SuggestionRepository.php

类中：

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

页面参数是默认参数，为集合生成

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

但是，页面参数现在是可以在web版本中编辑的唯一参数

我需要添加更多参数（

在本例中为level

）来招摇过市，并对其进行描述，以便用户/测试人员知道哪个参数实际指向该端点

主要问题:

---

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

级别

？最终解决了这个问题

我还没有找到它的文档，但我找到了一种方法

在实体类

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平台招摇过市文档中的结果视图：

在Api平台核心版本2.4.6中，向get注释添加“招摇过市上下文”对我来说不起作用。相反，我使用了在

就我而言，我不得不稍微偏离说明。在重写的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);
    }
}

---

如果某人需要执行类似操作，但使用XML配置：


如果有人希望URL中有一个额外的GET参数，例如，如果您的路由{id}参数没有被swagger测试工具解析，您应该在@pedrouan解决方案中更改此参数：

"in" = "path",

使用openapi_上下文并参考openapi文档：

 *              "openapi_context" = {
 *                  "parameters" = {
 *                      {
 *                          "name" = "nameOfQueryParameter",
 *                          "in" = "query",
 *                          "description" = "Description goes here",
 *                          "schema" = {
 *                              "type" = "string"
 *                          }
 *                      }
 *                  }
 *               }

您应该写下应该添加此内容的位置。@您是指配置文件的位置吗？我认为这有点超出了问题的范围。这个问题类似于“如何在不使用注释的情况下配置Api平台资源？”如果您是上一个版本，请将“swagger\u context”更改为“openapi\u context”。注意，
“required”=“true”
有效，因为字符串
“true”
的计算结果为true<代码>“required”=“false”
不起作用，它必须是
“required”=false
，文档就在这里：Api平台文档没有太多地涵盖Swagger/OpenAPI规范