如何使用大摇大摆的文档在 API 平台的endpoint中请求额外的 GET 参数？

Question

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

我有一个实体，并且有它的数据提供程序。我在为收集终结点定义其他参数时遇到问题。

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

endpoint是：

/suggestion

此endpoint侦听其他GET参数:

页面，级别

每次请求endpoint时都会读取这两个参数。

在我的< code > suggestions collection data provider . 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参数是默认参数，它是在集合的swagger中生成的。

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

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

我需要添加更多参数（在本例中为级别）来招摇和描述它们，以便用户/测试人员知道哪个参数实际进入此endpoint。

如何告诉api-platform，我希望api的用户/测试人员(从客户端)输入一些其他参数，例如< code>level？

Answer 1

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

<collectionOperation name="find_duplicated_items">
    <attribute name="method">GET</attribute>
    <attribute name="path">/items/find_duplicates</attribute>
    <attribute name="controller">App\Infrastructure\Http\Items\FindDuplicates</attribute>

     <attribute name="openapi_context">
        <attribute name="parameters">

            <attribute>
                <attribute name="name">someProperty</attribute>
                <attribute name="in">query</attribute>
                <attribute name="required">true</attribute>
                <attribute name="description">List foos and bars</attribute>
                <attribute name="schema">
                     <attribute name="type">array</attribute>
                     <attribute name="items">
                        <attribute name="type">integer</attribute>
                     </attribute>
                </attribute>
            </attribute>
        
            <attribute>
                <attribute name="name">ageDays</attribute>
                <attribute name="in">query</attribute>
                <attribute name="required">false</attribute>
                <attribute name="description">Max age in days</attribute>
                <attribute name="default">5</attribute>
                <attribute name="schema">
                    <attribute name="type">integer</attribute>
                </attribute>
            </attribute>
        </attribute>

    </attribute>

</collectionOperation>

这给了你这个:

Answer 2

在Api Platform核心版本2.4.6中，在get注释中添加“swagger_context”对我来说不起作用

就我而言，我不得不稍微偏离说明。在重写的规范化方法中，我必须先删除现有参数，然后将自定义定义添加到$doc参数数组中。正如pedrouan所做的那样，我能够添加require=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);
    }
}

注：

>

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

我添加了一个自定义数据提供程序，要求在对活动实体资源的所有api请求中设置事件属性过滤器。上述自定义不需要在进行直接获取或url get请求时设置它。

Answer 3

终于想通了。

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

在实体类＜code＞建议中。php＜/code＞我添加了一些注释行：

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平台swagger DOCs中的结果视图：