Nelmio api doc configuration example in symfony, with authentification schema and some refs.

CinemaController.php

<?php
// src/Controller/Api/CinemaController.php
namespace App\Controller\Api;

use App\Collection\CinemaCollection;
use FOS\RestBundle\Controller\{AbstractFOSRestController, Annotations as Rest};
use FOS\RestBundle\View\View;
use Nelmio\ApiDocBundle\Annotation\{Model, Security};
use OpenApi\Annotations as OA;

/**
 * @Rest\Route("/cinema")
 * @OA\Tag(name="Cinema")
 */
class CinemaController extends AbstractFOSRestController
{
    /**
     * @Rest\Get("/{id}", requirements={"id"="\d+"})
     * @Rest\View(serializerGroups={"Cinema", "CinemaDetails", "CinemaGroup", "Group"})
     * @OA\Parameter(name="Authorization", in="header", required=true, description="Authorization", @OA\Schema(type="string", default="Bearer TOKEN")),
     * @OA\Response(
     *     response=200,
     *     description="get Cinema by ID",
     *     @OA\JsonContent(ref=@Model(type=App\Entity\Cinema::class, groups={"Cinema", "CinemaDetails"}))
     * ),
     * @OA\Response(response=401, ref="#/components/responses/JwtTokenInvalid"),
     * @OA\Response(response=404, description="Cinema not found", @OA\JsonContent(ref="#/components/schemas/error"))
     * @Security(name="Bearer")
     */
    public function getById(int $id): View
    {
        //...
    }
}

nelmio_api_doc.yaml

# config/packages/nelmio_api_doc.yaml
nelmio_api_doc:
  documentation:
    info:
      title: My api
      description: "This is an awesome app!"
      version: "1.0"
    components:
      securitySchemes:
        Bearer:
          type: http
          scheme: bearer
          bearerFormat: JWT
      schemas:
        error:
          type: object
          properties:
            code:
              type: integer
            message:
              type: string
      responses:
        UnauthorizedError:
          description: Bad credentials
          content:
            application/json:
              schema:
                allOf: [ $ref: '#/components/schemas/error' ]
        JwtTokenInvalid:
          description: "JWT Token invalid, expired or not found"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/error'
    security:
      - Bearer: [ ]
    paths:
      /api/login_check:
        post:
          tags:
            - Authentication
          description: Login into the api, return a token.
          parameters:
            - in: query
              name: user
              description: Login
              required: true
              schema:
                type: object
                properties:
                  username:
                    type: string
                  password:
                    type: string
          responses:
            '200':
              description: Login successful, return a token with 1 day duration.
              content:
                application/json:
                  schema:
                    type: object
                    properties:
                      token:
                        type: string
            '401':
              $ref: '#/components/responses/UnauthorizedError'

  areas: # to filter documented areas
    path_patterns:
      - ^/api(?!/doc$) # Accepts routes under /api except /api/doc