title: Configuring api-platform to include header in OpenAPI (AKA Swagger) documentation
body: <p>I am using <a href="https://api-platform.com/docs" rel="nofollow noreferrer">API-Platform</a> with <a href="https://github.com/lexik/LexikJWTAuthenticationBundle" rel="nofollow noreferrer">JWTs</a> and have created a decorator to allow Swagger to display a <code>/authentication_token</code> endpoint as described by <a href="https://api-platform.com/docs/core/jwt/" rel="nofollow noreferrer">https://api-platform.com/docs/core/jwt/</a> and to a lesser degree <a href="https://api-platform.com/docs/core/openapi/" rel="nofollow noreferrer">https://api-platform.com/docs/core/openapi/</a>.  In addition to providing an email and password, I also need to provide a third parameter which is a UUID which identifies the account the user belongs to.  I was able to do so by including the UUID in the body, but I would rather have it included as a header such as <code>X-Account-UUID</code>.</p>
  <p>How can this be modified so that Swagger-UI includes this uuid property as a header and not in the body's JSON?</p>
  <pre><code>&lt;?php
  // api/src/OpenApi/JwtDecorator.php
  
  declare(strict_types=1);
  
  namespace App\OpenApi;
  
  use ApiPlatform\Core\OpenApi\Factory\OpenApiFactoryInterface;
  use ApiPlatform\Core\OpenApi\OpenApi;
  use ApiPlatform\Core\OpenApi\Model;
  
  final class JwtDecorator implements OpenApiFactoryInterface
  {
      private $decorated;
  
      public function __construct(OpenApiFactoryInterface $decorated)
      {
          $this-&gt;decorated = $decorated;
      }
  
      public function __invoke(array $context = []): OpenApi
      {
          $openApi = ($this-&gt;decorated)($context);
          $schemas = $openApi-&gt;getComponents()-&gt;getSchemas();
          /*
          echo(json_encode(['class'=&gt;get_class($this), 'methods'=&gt;get_class_methods($this)]));
          echo(json_encode(['class'=&gt;get_class($this-&gt;decorated), 'methods'=&gt;get_class_methods($this-&gt;decorated)]));
          echo(json_encode(['class'=&gt;get_class($openApi), 'methods'=&gt;get_class_methods($openApi)]));
          echo(json_encode(['class'=&gt;get_class($openApi-&gt;getComponents()), 'methods'=&gt;get_class_methods($openApi-&gt;getComponents())]));
          echo(json_encode(['class'=&gt;get_class($schemas), 'properties'=&gt;$schemas]));
          $securitySchemas = $openApi-&gt;getComponents()-&gt;getSecuritySchemes();
          echo(json_encode(['class'=&gt;get_class($securitySchemas), 'properties'=&gt;$securitySchemas]));
          $headers = $openApi-&gt;getComponents()-&gt;getHeaders();
          exit(json_encode(['class'=&gt;get_class($headers), 'properties'=&gt;$headers]));
          */
          $schemas['Token'] = new \ArrayObject([
              'type' =&gt; 'object',
              'properties' =&gt; [
                  'token' =&gt; [
                      'type' =&gt; 'string',
                      'readOnly' =&gt; true,
                  ],
              ],
          ]);
          $schemas['Credentials'] = new \ArrayObject([
              'type' =&gt; 'object',
              'properties' =&gt; [
                  'email' =&gt; [
                      'type' =&gt; 'string',
                      'example' =&gt; 'john.doe@bla.com',
                  ],
                  'password' =&gt; [
                      'type' =&gt; 'string',
                      'example' =&gt; 'secret',
                  ],
                  'uuid' =&gt; [
                      'type' =&gt; 'string',
                      'in' =&gt; 'header',
                      'example' =&gt; '1234abcd-abcd-1234-abcd-123412341234',
                  ],
              ],
              'headers' =&gt; [
                  'uuid' =&gt; [
                      'type' =&gt; 'string',
                      'in' =&gt; 'header',
                      'example' =&gt; '1234abcd-abcd-1234-abcd-123412341234',
                  ],
              ],
          ]);
  
          $responses = [
              '200' =&gt; [
                  'description' =&gt; 'Get JWT token',
                  'content' =&gt; [
                      'application/json' =&gt; [
                          'schema' =&gt; [
                              '$ref' =&gt; '#/components/schemas/Token',
                          ],
                      ],
                  ]
              ]
          ];
  
          $content = new \ArrayObject([
              'application/json' =&gt; [
                  'schema' =&gt; [
                      '$ref' =&gt; '#/components/schemas/Credentials',
                  ],
              ],
          ]);
  
          $requestBody = new Model\RequestBody('Generate new JWT Token', $content);
          $post = new Model\Operation('postCredentialsItem', [], $responses, 'Get JWT token to login.', '', new Model\ExternalDocumentation, [], $requestBody);
          $pathItem = new Model\PathItem('JWT Token', null, null, null, null, $post);
  
          $openApi-&gt;getPaths()-&gt;addPath('/authentication_token', $pathItem);
  
          return $openApi;
      }
  }
  </code></pre>