### NelmioApiDocBundle Installation

Source: https://github.com/nelmio/nelmioapidocbundle/blob/5.x/docs/index.rst

Instructions for installing the NelmioApiDocBundle using Composer.

```APIDOC
## Installation

### Description

Install the NelmioApiDocBundle using Composer.

### Method

```bash
composer require nelmio/api-doc-bundle
```

### Configuration

By default, only routes under ``/api`` are documented. Update the regexp at ``nelmio_api_doc.areas.path_patterns`` in ``config/packages/nelmio_api_doc.yaml`` to change this policy.

If not using Flex, add the bundle to your kernel:

```php
// AppKernel.php (or equivalent for your Symfony version)
public function registerBundles(): iterable
{
    $bundles = [
        // ...
        new Nelmio\ApiDocBundle\NelmioApiDocBundle(),
    ];
    // ...
}
```

### Registering Documentation Routes

To browse your documentation with a UI, register one of the following routes in ``config/routes.yaml``:

**Swagger UI:**
```yaml
app.swagger_ui:
    path: /api/doc
    methods: GET
    defaults: { _controller: nelmio_api_doc.controller.swagger_ui }
```

**ReDoc:**
```yaml
app.redocly:
    path: /api/doc
    methods: GET
    defaults: { _controller: nelmio_api_doc.controller.redocly }
```

**Stoplight:**
```yaml
app.stoplight:
    path: /api/doc
    methods: GET
    defaults: { _controller: nelmio_api_doc.controller.stoplight }
```

To expose the documentation in JSON format:

```yaml
app.swagger:
    path: /api/doc.json
    methods: GET
    defaults: { _controller: nelmio_api_doc.controller.swagger }
```

### Filtering Routes

To filter documented routes (e.g., exclude ``/_profiler/``), configure ``nelmio_api_doc.areas.path_patterns`` in ``config/packages/nelmio_api_doc.yaml``:

```yaml
nelmio_api_doc:
    areas:
        path_patterns:
            - ^/api(?!/doc$)
        host_patterns:
            - ^api\.
```

### Dependencies

Twig and Assets packages are needed for the Swagger UI.

```

--------------------------------

### Install Composer Dependencies for NelmioApiDocBundle

Source: https://github.com/nelmio/nelmioapidocbundle/blob/5.x/README.md

This command installs the Composer dependencies required to run the tests for the NelmioApiDocBundle. It is part of the setup process for contributing to or testing the bundle.

```bash
composer update
```

--------------------------------

### Install NelmioApiDocBundle using Composer

Source: https://github.com/nelmio/nelmioapidocbundle/blob/5.x/README.md

This command installs the latest version of the NelmioApiDocBundle using Composer, the dependency manager for PHP. Ensure you have Composer installed and in your system's PATH.

```bash
composer require nelmio/api-doc-bundle
```

--------------------------------

### Console command example in PHP

Source: https://github.com/nelmio/nelmioapidocbundle/blob/5.x/UPGRADE-3.0.md

Simple example of the api:doc:convert command to be run in the console to convert annotations.

```php
<?php
php bin/console api:doc:convert
?>

```

--------------------------------

### Install NelmioApiDocBundle Assets (Bash)

Source: https://github.com/nelmio/nelmioapidocbundle/blob/5.x/docs/faq.rst

Provides the command to manually install NelmioApiDocBundle's static assets (CSS, JS, images) if they are not automatically installed via Composer scripts. This resolves 404 or 406 errors for these assets.

```bash
$ php bin/console assets:install --symlink
```

--------------------------------

### Example Default Configuration (YAML)

Source: https://github.com/nelmio/nelmioapidocbundle/blob/5.x/docs/configuration_reference.rst

A sample YAML configuration block demonstrating various settings for the NelmioApiDocBundle.

```yaml
nelmio_api_doc:
    # Whether to use the symfony/type-info component for determining types.
    type_info: false
    # If true, `groups` passed to #[Model] attributes will be used to limit validation constraints
    use_validation_groups: false
    # Defines how to generate operation ids
    operation_id_generation: always_prepend
    cache:
        # define cache pool to use
        pool: null
        # define cache item id
        item_id: null
    # The documentation to use as base
    documentation:
        # Example:
        # info:
        #   title: 'My App'
        #   description: 'My App Description'
     # List of enabled Media Types
    media_types:
        - json
    # UI configuration options
    html_config:
        assets_mode: cdn
        # https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/
        swagger_ui_config: []
        # https://redocly.com/docs/redoc/config/
        redocly_config: []
        # https://docs.stoplight.io/docs/elements/b074dc47b2826-elements-configuration-options
        stoplight_config: []
    # Filter the routes that are documented
    areas:
        default:
            path_patterns:
                # Examples:
                # - ^/api
                # - '^/api(?!/admin)'
            host_patterns:
                # Example:
                # - ^api
            name_patterns:
                # Example:
                # - ^api_v1
            # whether to filter by attributes
            with_attribute: false
            security:
                # Authentication schemes https://swagger.io/docs/specification/v3_0/authentication/
                MyBearerScheme:
                    type: 'http'
                    scheme: 'bearer'
            # if set disables default routes without attributes
            disable_default_routes: false
            # The base documentation used for the area
            documentation:
                # Example:
                # info:
                #   title: 'My App'
                #   description: 'My App Description'
            cache:
                # define cache pool to use for the area
                pool: null
                # define cache item id for the area
                item_id: null
    models:
        use_jms: false
        names:
            - 
                alias: ~ # Example: 'Foo'
                type: ~ # Example: 'App\Foo'
                groups: null
                options: null
                serializationContext: []
                areas: []
```

--------------------------------

### JSON Example for API Security Definitions

Source: https://github.com/nelmio/nelmioapidocbundle/blob/5.x/docs/security.rst

An example JSON snippet illustrating the structure for defining API security schemes and paths within an API documentation specification, likely OpenAPI/Swagger.

```json
{
    "paths": {
        "/api/users": {
            "post": {
                "security": [
                    {
                        "BearerAuthCustom": [
                            "bearer:read"
                        ]
                    }
                ]
            }
        }
    },
    "components": {
         "securitySchemes": {
              "ApiKeyAuth": {
                    "type": "apiKey",
                    "name": "X-API-KEY",
                    "in": "header"
                }
          }
    }
}
```

--------------------------------

### Configure Redocly route

Source: https://github.com/nelmio/nelmioapidocbundle/blob/5.x/docs/index.rst

This YAML configuration sets up a route for Redocly, another UI for viewing OpenAPI documentation. Accessing `/api/doc` via GET requests will render the Redocly interface.

```yaml
# config/routes.yaml
app.redocly:
    path: /api/doc
    methods: GET
    defaults: { _controller: nelmio_api_doc.controller.redocly }
```

--------------------------------

### Run NelmioApiDocBundle Tests with PHPUnit

Source: https://github.com/nelmio/nelmioapidocbundle/blob/5.x/README.md

This command executes the test suite for the NelmioApiDocBundle using PHPUnit. This is typically run after installing dependencies to ensure the bundle is functioning correctly or to verify changes during development.

```bash
composer phpunit
```

--------------------------------

### Configure Stoplight route

Source: https://github.com/nelmio/nelmioapidocbundle/blob/5.x/docs/index.rst

This configuration defines a route for Stoplight's documentation viewer. By accessing `/api/doc` with a GET request, you can use Stoplight to explore your API.

```yaml
# config/routes.yaml
app.stoplight:
    path: /api/doc
    methods: GET
    defaults: { _controller: nelmio_api_doc.controller.stoplight }
```

--------------------------------

### Fixing Asset Loading Issues

Source: https://github.com/nelmio/nelmioapidocbundle/blob/5.x/docs/faq.rst

Provides instructions on how to resolve 404 or 406 HTTP errors related to NelmioApiDocBundle's static assets (CSS, JS, images) by manually installing them.

```APIDOC
## Fixing Asset Loading Issues (404/406 Errors)

### Description
This section addresses common issues where NelmioApiDocBundle's static assets (like CSS, JavaScript, and images) fail to load, resulting in 404 (Not Found) or 406 (Not Acceptable) HTTP status codes. This typically occurs when the assets are not automatically installed during the Composer process.

### Cause
The assets are usually installed via a Composer script (`ScriptHandler::installAssets`) triggered by `post-install-cmd` or `post-update-cmd`. If this script is not configured or executed properly, the assets will not be placed in the web directory.

### Solution
Manually trigger the asset installation command using the Symfony CLI:

### Command
```bash
$ php bin/console assets:install --symlink
```

**Explanation:**
*   `php bin/console`: Executes the Symfony console commands.
*   `assets:install`: The command responsible for copying assets from vendor directories to the public web directory.
*   `--symlink`: Creates symbolic links instead of copying files, which is often useful during development for direct updates.
```

--------------------------------

### Configure Area Security Scheme (YAML)

Source: https://github.com/nelmio/nelmioapidocbundle/blob/5.x/docs/configuration_reference.rst

Sets up a security scheme for a specific API documentation area. This example defines a bearer authentication scheme.

```yaml
nelmio_api_doc:
    # ...

    areas:
        default:
            security:
                MyBearerScheme:
                    type: 'http'
                    scheme: 'bearer'
```

--------------------------------

### Complete Symfony Controller Example with Attributes

Source: https://github.com/nelmio/nelmioapidocbundle/blob/5.x/docs/symfony_attributes.rst

Demonstrates a comprehensive example of using various NelmioApiDocBundle attributes within a Symfony controller for API documentation, including query string, query parameters, and request payloads.

```php-attributes
namespace AppBundle\Controller;

use AppBundle\UserDTO;
use AppBundle\UserQuery;
use OpenApi\Attributes as OA;
use Symfony\Component\HttpKernel\Attribute\MapQueryParameter;
use Symfony\Component\HttpKernel\Attribute\MapQueryString;
use Symfony\Component\HttpKernel\Attribute\MapRequestPayload;
use Symfony\Component\HttpKernel\Attribute\MapUploadedFile;
use Symfony\Component\Routing\Annotation\Route;

class UserController
{
    /**
     * Find user with MapQueryString.
     */
    #[Route('/api/users', methods: ['GET'])]
    #[OA\Parameter(
        name: 'userId',
        description: 'Id of the user to find',
        in: 'query',
    )]
    public function findUser(#[MapQueryString] UserQuery $userQuery)
    {
        // ...
    }

    /**
     * Find user with MapQueryParameter.
     */
    #[Route('/api/users/v2', methods: ['GET'])]
    #[OA\Parameter(
        name: 'userId',
        description: 'Id of the user to find',
        in: 'query',
    )]

```

--------------------------------

### Configure Operation ID Generation (YAML)

Source: https://github.com/nelmio/nelmioapidocbundle/blob/5.x/docs/configuration_reference.rst

Example of setting the operation ID generation strategy to 'always_prepend' in the YAML configuration file.

```yaml
# config/packages/nelmio_api_doc.yaml
nelmio_api_doc:
    operation_id_generation: always_prepend
```

--------------------------------

### Configure Swagger UI Interface Endpoint

Source: https://context7.com/nelmio/nelmioapidocbundle/llms.txt

This snippet shows how to configure the route for the Swagger UI interface using `routes.yaml` and provides an example of NelmioApiDocBundle configuration in `nelmio_api_doc.yaml`. It allows access to interactive API documentation with support for multiple documentation areas and rendering options.

```yaml
# In your config/routes.yaml:
api_doc:
    path: /api/doc/{area}
    controller: Nelmio\ApiDocBundle\Controller\SwaggerUiController
    defaults:
        area: default
    methods: GET

# Access the documentation:
# Default area: GET /api/doc
# Custom area: GET /api/doc/admin

# Configure in config/packages/nelmio_api_doc.yaml:
nelmio_api_doc:
    documentation:
        info:
            title: My API
            version: 1.0.0
    areas:
        default:
            path_patterns: ['^/api']
        admin:
            path_patterns: ['^/api/admin']
    html_config:
        assets_mode: cdn
        swagger_ui_config:
            deepLinking: true
            displayRequestDuration: true
```

--------------------------------

### Model Documentation with Validation Groups

Source: https://github.com/nelmio/nelmioapidocbundle/blob/5.x/docs/index.rst

This example demonstrates how to use validation groups with the #[Model] attribute when the 'use_validation_groups' configuration is enabled. It shows how constraints are applied based on specified groups.

```php-attributes
use Symfony\Component\Serializer\Annotation\Groups;
use Symfony\Component\Validator\Constraints as Assert;
use OpenApi\Attributes as OA;

class UserDto
{
    #[Groups(['default', 'create', 'update'])]
    #[Assert\NotBlank(groups: ['default', 'create'])]
    public string $username;
}

// OpenAPI schema example using the model
// shows `username` as `required` in the OpenAPI schema (not nullable)
```

--------------------------------

### Configure JSON Documentation Export Endpoint

Source: https://context7.com/nelmio/nelmioapidocbundle/llms.txt

This configuration sets up a route in `routes.yaml` to export the OpenAPI specification in JSON format. This is useful for programmatic access, CI/CD integration, or consumption by other tools. The example demonstrates a basic JSON structure of the OpenAPI spec.

```yaml
# In your config/routes.yaml:
api_doc_json:
    path: /api/doc.json
    controller: Nelmio\ApiDocBundle\Controller\DocumentationController
    defaults:
        area: default
    methods: GET

# Fetch the documentation:
# curl http://localhost/api/doc.json
# Response (JSON):
{
    "openapi": "3.0.0",
    "info": {
        "title": "My API",
        "version": "1.0.0"
    },
    "paths": {
        "/api/users": {
            "get": {
                "operationId": "get-api-users",
                "responses": {
                    "200": {
                        "description": "Success"
                    }
                }
            }
        }
    }
}
```

--------------------------------

### Customize Swagger UI Font (Twig)

Source: https://github.com/nelmio/nelmioapidocbundle/blob/5.x/docs/faq.rst

Shows how to customize the font used in the NelmioApiDocBundle's Swagger UI by overriding the `index.html.twig` template. This example re-adds Google Fonts after they were removed for GDPR compliance.

```twig
{# templates/bundles/NelmioApiDocBundle/SwaggerUi/index.html.twig #}
{#
   To avoid a "reached nested level" error an exclamation mark `!` has to be added
   See https://symfony.com/blog/new-in-symfony-3-4-improved-the-overriding-of-templates
#}
{% extends '@!NelmioApiDoc/SwaggerUi/index.html.twig' %}

{% block stylesheets %}
    <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:400,700|Source+Code+Pro:300,600|Titillium+Web:400,600,700">
    {{ parent() }}
    <style type="text/css" rel="stylesheet">
        #formats {
            font-family: Open Sans,sans-serif;
        }

        .swagger-ui .opblock-tag,
        .swagger-ui .opblock .opblock-section-header label,
        .swagger-ui .opblock .opblock-section-header h4,
        .swagger-ui .opblock .opblock-summary-method,
        .swagger-ui .tab li,
        .swagger-ui .scheme-container .schemes>label,

```

--------------------------------

### Configure YAML Documentation Export Endpoint

Source: https://context7.com/nelmio/nelmioapidocbundle/llms.txt

This snippet defines a route in `routes.yaml` for exporting the OpenAPI specification in YAML format. YAML is preferred for human readability and easier version control. The example shows a sample YAML output of the OpenAPI specification.

```yaml
# In your config/routes.yaml:
api_doc_yaml:
    path: /api/doc.yaml
    controller: Nelmio\ApiDocBundle\Controller\YamlDocumentationController
    defaults:
        area: default
    methods: GET

# Fetch YAML documentation:
# curl http://localhost/api/doc.yaml
# Response (YAML):
openapi: 3.0.0
info:
  title: My API
  version: 1.0.0
paths:
  /api/users:
    get:
      operationId: get-api-users
      responses:
        '200':
          description: Success
```

--------------------------------

### Specify Media Type for Response Schemas

Source: https://github.com/nelmio/nelmioapidocbundle/blob/5.x/UPGRADE-4.0.md

When defining response schemas, explicitly use '@OA\JsonContent' or '@OA\XmlContent' instead of '@OA\Schema' to specify the media type. This ensures correct documentation for different content types.

```php
/**
 * @OA\Response(
 *     response=200,
 *     description="Successful operation",
 *     @OA\Schema(ref="#/components/schemas/MyModel")
 * )
 */
```

```php
/**
 * @OA\Response(
 *     response=200,
 *     description="Successful operation",
 *     @OA\JsonContent(ref="#/components/schemas/MyModel")
 * )
 */
```

```php
/**
 * @OA\Response(
 *     response=200,
 *     description="Successful operation",
 *     @OA\XmlContent(ref="#/components/schemas/MyModel")
 * )
 */
```

--------------------------------

### PHP Controller Example for User Creation

Source: https://github.com/nelmio/nelmioapidocbundle/blob/5.x/docs/symfony_attributes.rst

This PHP controller snippet shows how to create a new user using a POST request to '/api/users'. It utilizes #[MapRequestPayload] to map the request body to a UserDTO object and includes #[OARequestBody] for OpenAPI documentation. This requires PHP 8.1 for attribute support.

```php
/**
 * Create a new user.
 */
#[Route('/api/users', methods: ['POST'])]
#[OA\RequestBody(
    groups: ['create'],
)]
public function createUser(#[MapRequestPayload] UserDTO $user)
{
    // ...
}
```

--------------------------------

### GET /api/users

Source: https://github.com/nelmio/nelmioapidocbundle/blob/5.x/docs/symfony_attributes.rst

Find a user by their ID. This endpoint uses query parameters for user identification.

```APIDOC
## GET /api/users

### Description
Find a user by their ID.

### Method
GET

### Endpoint
/api/users

#### Query Parameters
- **userId** (int) - Required - The ID of the user to find.

### Request Example
```json
{
  "userId": 123
}
```

### Response
#### Success Response (200)
- **user** (object) - Details of the found user.

#### Response Example
```json
{
  "user": {
    "id": 123,
    "name": "John Doe"
  }
}
```
```

--------------------------------

### Sharing Parameter Configuration

Source: https://github.com/nelmio/nelmioapidocbundle/blob/5.x/docs/faq.rst

Demonstrates how to define reusable schemas in the configuration to avoid duplicating descriptions across multiple endpoints.

```APIDOC
## Sharing Parameter Configuration

### Description
This section explains how to define reusable schemas in the `nelmio_api_doc.yaml` configuration file to avoid repetitive descriptions for common parameter structures across different API endpoints.

### Usage
1. Define a schema under `nelmio_api_doc.documentation.components.schemas`.
2. Reference the defined schema using `$ref` in your controller annotations (`@OA\JsonContent(ref="#/components/schemas/YourSchemaName")`).

### Example (YAML Configuration)
```yaml
# config/nelmio_api_doc.yaml
nelmio_api_doc:
    documentation:
        components:
            schemas:
                NelmioImageList:
                    description: "Response for some queries"
                    type: object
                    properties:
                        total:
                            type: integer
                            example: 42
                        items:
                            type: array
                            items:
                                $ref: "#/components/schemas/ImageMetadata"
```

### Example (PHP Controller Annotation)
```php
<?php

use OpenApiAnnotations as OA;

class NelmioController
{
    /**
     * @OA\Response(
     *     response=200,
     *     description="List of image definitions",
     *     @OA\JsonContent(
     *       ref="#/components/schemas/NelmioImageList"
     *     )
     * )
     */
    public function getImageListAction(): Response
    {
        // ... implementation
    }
}
```
```

--------------------------------

### GET /api/{user}/rewards

Source: https://github.com/nelmio/nelmioapidocbundle/blob/5.x/docs/index.rst

Fetches the rewards for a specific user. This endpoint lists confirmed awards and allows for ordering.

```APIDOC
## GET /api/{user}/rewards

### Description

Lists the rewards of the specified user. This call takes into account all confirmed awards, but not pending or refused awards.

### Method

GET

### Endpoint

/api/{user}/rewards

### Parameters

#### Path Parameters

- **user** (User) - Required - The user whose rewards are to be fetched.

#### Query Parameters

- **order** (string) - Optional - The field used to order rewards.

### Request Example

```json
{
  "example": "request body"
}
```

### Response

#### Success Response (200)

- **rewards** (array) - An array of reward items, each potentially conforming to the `AlbumDto` model with `full` serialization groups.

#### Response Example

```json
{
  "example": "response body"
}
```
```

--------------------------------

### Handle Optional Path Parameters with Separate Actions (PHP)

Source: https://github.com/nelmio/nelmioapidocbundle/blob/5.x/docs/faq.rst

Illustrates the recommended approach for handling optional path parameters in NelmioApiDocBundle by defining separate controller actions for the required and optional cases. This adheres to OpenAPI specifications which do not directly support optional path parameters.

```php
/**
 * Get all user meta data.
 *
 * @Route("/{user}/meta",
 *     methods={"GET"},
 *     name="get_user_metadata"
 * )
 *
 * @OA\Response(
 *     response=200,
 *     description="Json hashmap with all user meta data",
 *     @OA\JsonContent(@OA\Schema(
 *        type="object",
 *        example={"foo": "bar", "hello": "world"}
 *     ))
 * )
 */
public function cgetAction(string $user)
{
    return $this->getAction($user, null);
}

/**
 * Get user meta for a specific field.
 *
 * @Route("/{user}/meta/{metaName}",
 *     methods={"GET"},
 *     name="get_user_metadata_single"
 * )
 *
 * @OA\Response(
 *     response=200,
 *     description="A json string with the value of the requested field",
 *     @OA\JsonContent(@OA\Schema(
 *          type="string"
 *     ))
 * )
 */
public function getAction(string $user, string $metaName = null)
{
    ...
}
```

--------------------------------

### Handling Optional Path Parameters

Source: https://github.com/nelmio/nelmioapidocbundle/blob/5.x/docs/faq.rst

Explains the limitation of optional path parameters in OpenAPI and provides a recommended solution by defining separate controller actions for different endpoint variations.

```APIDOC
## Handling Optional Path Parameters

### Description
OpenAPI specification does not directly support optional path parameters. To achieve the effect of optional path parameters in Swagger UI, you need to define two separate controller actions: one for the route with the optional parameter omitted, and another for the route including the optional parameter. This ensures proper documentation for both scenarios.

### Problem Statement
When a controller action has an optional path parameter (e.g., `string $metaName = null`), Swagger UI might incorrectly display it as a required parameter.

### Recommended Solution
Define two distinct routes and controller actions:

1.  **Action for the general case (optional parameter omitted):** Documented with the base path.
2.  **Action for the specific case (optional parameter included):** Documented with the full path including the optional parameter.

### Example (Controller Implementation)
```php
<?php

use Symfony\Component\Routing\Annotation\Route;
use OpenApi\Annotations as OA;

class UserController
{
    /**
     * Get all user meta data.
     *
     * @Route("/{user}/meta",
     *     methods={"GET"},
     *     name="get_user_metadata"
     * )
     *
     * @OA\Response(
     *     response=200,
     *     description="Json hashmap with all user meta data",
     *     @OA\JsonContent(@OA\Schema(
     *        type="object",
     *        example={"foo": "bar", "hello": "world"}
     *     ))
     * )
     */
    public function cgetAction(string $user): Response
    {
        // Call the more specific action with null for metaName
        return $this->getAction($user, null);
    }

    /**
     * Get user meta for a specific field.
     *
     * @Route("/{user}/meta/{metaName}",
     *     methods={"GET"},
     *     name="get_user_metadata_single"
     * )
     *
     * @OA\Response(
     *     response=200,
     *     description="A json string with the value of the requested field",
     *     @OA\JsonContent(@OA\Schema(
     *          type="string"
     *     ))
     * )
     */
    public function getAction(string $user, string $metaName = null): Response
    {
        // ... implementation to retrieve metadata
    }
}
```

**Note:** The `cgetAction` is primarily for documentation purposes in OpenAPI. The `getAction` handles the actual logic for both scenarios.
```

--------------------------------

### Configure Operation ID Generation (PHP)

Source: https://github.com/nelmio/nelmioapidocbundle/blob/5.x/docs/configuration_reference.rst

Example of setting the operation ID generation strategy using the OperationIdGeneration enum in PHP service configuration.

```php
// config/services.php
use Nelmio\ApiDocBundle\Describer\OperationIdGeneration;

return function (ContainerConfigurator $container) {
    $containerConfigurator->extension('nelmio_api_doc', [
        'operation_id_generation' => OperationIdGeneration::ALWAYS_PREPEND,
    ]);
};
```

--------------------------------

### Configure Swagger UI route

Source: https://github.com/nelmio/nelmioapidocbundle/blob/5.x/docs/index.rst

This configuration registers a route for the Swagger UI, allowing you to browse your API documentation interactively. The path `/api/doc` will serve the UI.

```yaml
# config/routes.yaml
app.swagger_ui:
    path: /api/doc
    methods: GET
    defaults: { _controller: nelmio_api_doc.controller.swagger_ui }
```

--------------------------------

### Configure Base API Documentation (YAML)

Source: https://github.com/nelmio/nelmioapidocbundle/blob/5.x/docs/configuration_reference.rst

Specifies the base API documentation to be used, allowing for the inclusion of OpenAPI/Swagger metadata such as title and description.

```yaml
nelmio_api_doc:
    # ...

    documentation:
        # Any valid OpenAPI/Swagger documentation
        info:
            title: 'My App'
            description: 'My App Description'
```

--------------------------------

### Dump API Docs in HTML (Bash)

Source: https://github.com/nelmio/nelmioapidocbundle/blob/5.x/docs/commands.rst

Dumps the API documentation in HTML format using the NelmioApiDocBundle command. The `--format=html` option specifies the output format. The `--html-config` option allows customization of HTML output, such as disabling the sandbox feature or setting the server URL.

```bash
$ php bin/console nelmio:apidoc:dump --format=html > api.html
$ php bin/console nelmio:apidoc:dump --format=html --html-config '{"assets_mode":"offline","server_url":"https://example.com","swagger_ui_config":{"supportedSubmitMethods":[]}}' > api.html
```

--------------------------------

### Opting Out of JMS Serializer Per Endpoint

Source: https://github.com/nelmio/nelmioapidocbundle/blob/5.x/docs/index.rst

Provides an example of how to opt out of using the JMS serializer for a specific API endpoint by setting 'useJms' to false within the serializationContext of an OA\Response attribute.

```php-attributes
#[OA\Response(response: 200, content: new Model(type: UserDto::class, serializationContext: ['useJms' => false]))]
```

--------------------------------

### Dump API Docs in YAML (Bash)

Source: https://github.com/nelmio/nelmioapidocbundle/blob/5.x/docs/commands.rst

Dumps the API documentation in YAML format using the NelmioApiDocBundle command. The `--format=yaml` option specifies the output format. The `--server-url` option can override the default API URL if the static documentation is hosted elsewhere.

```bash
$ php bin/console nelmio:apidoc:dump --format=yaml --server-url "http://example.com/api" > api.yaml
```

--------------------------------

### Model Documentation with #[Model] Attribute (Type)

Source: https://github.com/nelmio/nelmioapidocbundle/blob/5.x/docs/index.rst

This example shows how to use the #[Model] attribute to automatically deduce model properties for API documentation. The 'type' option specifies the class of the model.

```php-attributes
use OpenApi\Attributes as OA;
use Nelmio\ApiDocBundle\Attribute\Model;

// ...

#[OA\Response(
    response: 200,
    description: 'Successful response',
    content: new Model(type: User::class)
)]
```

--------------------------------

### PHP Controller Security without #[IsGranted] (Attributes)

Source: https://github.com/nelmio/nelmioapidocbundle/blob/5.x/docs/security.rst

An example of a PHP controller that does not use the #[IsGranted] attribute, resulting in no automatically generated security definitions for its routes. This is useful for public endpoints.

```php-attributes
use Symfony\Component\Routing\Annotation\Route;

class UserController
{
    #[Route('/api/users', methods: ['POST'])]
    public function createUser()
    {
        // ...
    }
}
```

--------------------------------

### NelmioApiDocBundle Configuration Options

Source: https://github.com/nelmio/nelmioapidocbundle/blob/5.x/docs/index.rst

Configuration options for NelmioApiDocBundle, including global documentation information and security schemes.

```APIDOC
## Configuration

### Global Documentation Information

Configure global information in the ``documentation.info`` section of the bundle configuration.

```yaml
# config/packages/nelmio_api_doc.yaml
nelmio_api_doc:
    documentation:
        servers:
          - url: http://api.example.com/unsafe
            description: API over HTTP
          - url: https://api.example.com/secured
            description: API over HTTPS
        info:
            title: My App
            description: This is an awesome app!
            version: 1.0.0
            x-build: #CommitHash
        components:
            securitySchemes:
                Bearer:
                    type: http
                    scheme: bearer
                    bearerFormat: JWT
        security:
            - Bearer: []
```

Refer to the `OpenAPI 3.0 specification`_ for available fields.

.. _`OpenAPI 3.0 specification`: https://swagger.io/docs/specification
```

--------------------------------

### Configure Reusable Schemas in NelmioApiDocBundle (YAML)

Source: https://github.com/nelmio/nelmioapidocbundle/blob/5.x/docs/faq.rst

Demonstrates how to define reusable schema components in the NelmioApiDocBundle configuration (nelmio_api_doc.yaml). This allows you to avoid duplicating schema definitions across multiple endpoints by referencing them using `$ref`.

```yaml
# config/nelmio_api_doc.yaml
nelmio_api_doc:
    documentation:
        components:
            schemas:
                NelmioImageList:
                    description: "Response for some queries"
                    type: object
                    properties:
                        total:
                            type: integer
                            example: 42
                        items:
                            type: array
                            items:
                                $ref: "#/components/schemas/ImageMetadata"
```

--------------------------------

### User API Endpoint (GET /api/users/{id})

Source: https://context7.com/nelmio/nelmioapidocbundle/llms.txt

Retrieves user details by ID. The response schema is generated using the #[Model] attribute, specifying the `User` class and the `user:read` serialization group.

```APIDOC
## GET /api/users/{id}

### Description
Returns user details for a specific user ID.

### Method
GET

### Endpoint
`/api/users/{id}`

### Parameters
#### Path Parameters
- **id** (int) - Required - The ID of the user to retrieve.

### Response
#### Success Response (200)
- **id** (int) - The user's unique identifier.
- **email** (string) - The user's email address.
- **createdAt** (DateTimeInterface) - The timestamp when the user was created.

### Response Example
```json
{
    "id": 1,
    "email": "user@example.com",
    "createdAt": "2023-10-27T10:00:00+00:00"
}
```
```

--------------------------------

### Basic Dump Command (Bash)

Source: https://github.com/nelmio/nelmioapidocbundle/blob/5.x/docs/commands.rst

A basic command to dump the API documentation using NelmioApiDocBundle. The default format is JSON. Additional options can be appended to customize the output.

```bash
$ php bin/console nelmio:apidoc:dump [--format="..."]
```

--------------------------------

### Configure API Documentation Areas with Path and Host Patterns

Source: https://context7.com/nelmio/nelmioapidocbundle/llms.txt

This YAML configuration defines different documentation areas ('default', 'admin', 'partner') with specific route filtering based on path patterns, host patterns, and attributes. It also demonstrates how to set documentation information and security schemes per area.

```yaml
nelmio_api_doc:
    documentation:
        info:
            title: Multi-Tenant API
            version: 2.0.0
        servers:
            - url: https://api.example.com
              description: Production server

    areas:
        # Default public API area
        default:
            path_patterns:
                - ^/api/v1
                - ^/api/v2(?!/admin)  # Exclude admin routes
            host_patterns:
                - ^api\.example\.com$
            documentation:
                info:
                    title: Public API

        # Admin-only area
        admin:
            path_patterns:
                - ^/api/admin
            with_attribute: true  # Only routes with #[Areas(['admin'])]
            name_patterns:
                - ^admin_  # Route names starting with 'admin_'
            security:
                adminAuth:
                    type: http
                    scheme: bearer
            documentation:
                info:
                    title: Administration API
                    description: Internal admin endpoints

        # Partner integration area
        partner:
            with_attribute: true
            disable_default_routes: true
            documentation:
                info:
                    title: Partner Integration API

# Example route matching:
# /api/v1/users → default area
# /api/admin/users with #[Areas(['admin'])] → admin area
# /api/v2/admin/users → excluded from default (negative lookahead)
```

--------------------------------

### Using @Model Annotation for JSON Responses

Source: https://github.com/nelmio/nelmioapidocbundle/blob/5.x/UPGRADE-4.0.md

When using the '@Model' annotation directly within '@OA\Response', the media type defaults to 'json'. This simplifies the definition for common JSON responses.

```php
/**
 * @OA\Response(
 *     response=200,
 *     description="Successful operation",
 *     @OA\Model(ref="#/components/schemas/MyModel")
 * )
 */
```

--------------------------------

### Configure HTML UI Assets Mode (YAML)

Source: https://github.com/nelmio/nelmioapidocbundle/blob/5.x/docs/configuration_reference.rst

Sets the configuration for the HTML documentation UI, specifically controlling how assets are loaded. It supports CDN or local asset modes and can include specific configurations for Swagger UI, Redocly, and Stoplight.

```yaml
nelmio_api_doc:
    # ...

    html_config:
        assets_mode: 'cdn'
        # https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/
        swagger_ui_config: []
        # https://redocly.com/docs/redoc/config/
        redocly_config: []
        # https://docs.stoplight.io/docs/elements/b074dc47b2826-elements-configuration-options
        stoplight_config: []
```

--------------------------------

### Update Namespace for Swagger Annotations

Source: https://github.com/nelmio/nelmioapidocbundle/blob/5.x/UPGRADE-4.0.md

Update 'use' statements and annotation references from the old Swagger namespace to the new OpenApi namespace. This is a crucial step for compatibility with OpenAPI 3.0.

```php
use Swagger\Annotations as SWG;

// ...

/**
 * @SWG\Response(...)
 */
public function exampleAction()
{
    // ...
}
```

```php
use OpenApi\Annotations as OA;

// ...

/**
 * @OA\Response(...)
 */
public function exampleAction()
{
    // ...
}
```

--------------------------------

### Configure API documentation information

Source: https://github.com/nelmio/nelmioapidocbundle/blob/5.x/docs/index.rst

This YAML configuration allows you to set global information for your API documentation, such as servers, title, description, version, and build information. It also includes component definitions for security schemes like JWT Bearer tokens.

```yaml
nelmio_api_doc:
    documentation:
        servers:
          - url: http://api.example.com/unsafe
            description: API over HTTP
          - url: https://api.example.com/secured
            description: API over HTTPS
        info:
            title: My App
            description: This is an awesome app!
            version: 1.0.0
            x-build: #CommitHash
        components:
            securitySchemes:
                Bearer:
                    type: http
                    scheme: bearer
                    bearerFormat: JWT
        security:
            - Bearer: []
```

--------------------------------

### Update Configuration: 'with_annotation' to 'with_attribute'

Source: https://github.com/nelmio/nelmioapidocbundle/blob/5.x/UPGRADE-5.0.md

This example shows how to update the NelmioApiDocBundle configuration file. The option `with_annotation` has been renamed to `with_attribute` to reflect the shift from annotations to attributes. This change affects the `areas.path_patterns` configuration.

```yaml
nelmio_api_doc:
    areas:
        path_patterns:
            - ^/api/foo
       with_annotation: true
```

```yaml
nelmio_api_doc:
    areas:
        path_patterns:
            - ^/api/foo
       with_attribute: true
```

--------------------------------

### Configure HTML Documentation UI in NelmioApiDocBundle

Source: https://context7.com/nelmio/nelmioapidocbundle/llms.txt

Customizes the appearance and behavior of Swagger UI, Redocly, or Stoplight Elements interfaces. This configuration is managed via the `html_config` section in `nelmio_api_doc.yaml`, allowing fine-grained control over asset loading, UI specific settings, and theme customization.

```yaml
nelmio_api_doc:
    html_config:
        # Asset loading strategy
        assets_mode: cdn  # Options: cdn, offline, bundle

        # Swagger UI customization
        swagger_ui_config:
            deepLinking: true
            displayOperationId: true
            displayRequestDuration: true
            filter: true
            showExtensions: true
            showCommonExtensions: true
            tryItOutEnabled: true
            persistAuthorization: true
            layout: BaseLayout
            defaultModelsExpandDepth: 1
            defaultModelExpandDepth: 3
            docExpansion: list  # none, list, full
            tagsSorter: alpha
            operationsSorter: alpha

        # Redocly configuration
        redocly_config:
            theme:
                colors:
                    primary:
                        main: '#dd5522'
            hideDownloadButton: false
            disableSearch: false
            expandResponses: '200,201'

        # Stoplight Elements configuration
        stoplight_config:
            router: hash
            layout: sidebar
            hideInternal: false
            hideTryIt: false

# Change UI renderer in routes:
api_doc_swagger:
    path: /api/doc/swagger
    controller: Nelmio\ApiDocBundle\Controller\SwaggerUiController
    defaults:
        area: default
        # Renderer set via DI configuration, typically 'swagger_ui'

# For offline mode, assets are bundled:
# npm install swagger-ui-dist
# Copy to public/bundles/nelmioapidoc/

```

--------------------------------

### Export API Documentation to Compact JSON

Source: https://context7.com/nelmio/nelmioapidocbundle/llms.txt

This command exports the API documentation in JSON format without pretty printing, resulting in a compact file suitable for machine processing. The output is saved to 'openapi.min.json'.

```bash
php bin/console nelmio:apidoc:dump --no-pretty > docs/openapi.min.json
```

--------------------------------

### Configure API Documentation Areas (YAML)

Source: https://github.com/nelmio/nelmioapidocbundle/blob/5.x/docs/configuration_reference.rst

Defines different 'areas' for API documentation, allowing granular control over which routes are documented. Each area can have custom path, host, and name patterns, as well as specific security, documentation, and cache settings.

```yaml
nelmio_api_doc:
    # ...

    areas:
        default:
            path_patterns:
                # Examples:
                # - ^/api
                # - '^/api(?!/admin)'
            host_patterns:
                # Example:
                # - ^api\.
            name_patterns:
                # Example:
                # - ^api_v1
            with_attribute: false
            security:
                MyBearerScheme:
                    type: 'http'
                    scheme: 'bearer'
            disable_default_routes: false
            documentation:
                # Example:
                # info:
                #   title: 'My App'
                #   description: 'My App Description'
            cache:
                # define cache pool to use for the area
                pool: null
                # define cache item id for the area
                item_id: null
```

--------------------------------

### Locate Nelmio Annotation in PHP Code

Source: https://github.com/nelmio/nelmioapidocbundle/blob/5.x/UPGRADE-3.0.md

This function locates the start and end positions of a Nelmio API documentation annotation within a PHP code string. It searches for the `@ApiDoc` or `@Operation` annotation associated with a specific method.

```php
<?php
    /**
     * @return array with `start` position and `length`
     */
    private function locateNelmioAnnotation(string $code, string $methodName): array
    {
        $position = strpos($code, "tion $methodName(");
        if (false === $position) {
            throw new \RuntimeException("Method $methodName not found in controller.");
        }

        $docstart = strrpos(substr($code, 0, $position), '@ApiDoc');
        if (false === $docstart) {
            //If action is defined more than once. Should continue and don't throw exception
            $docstart = strrpos(substr($code, 0, $position), '@Operation');
            if (false === $docstart) {

                throw new \RuntimeException("Method $methodName has no @ApiDoc annotation around\n".substr($code, $position - 200, 150));
            }
        }
        $docend = strpos($code, '* )', $docstart) + 3;

        return [
            'start' => $docstart,
            'length' => $docend - $docstart,
        ];
    }
?>

```

--------------------------------

### Define Multiple API Documentation Areas (YAML)

Source: https://github.com/nelmio/nelmioapidocbundle/blob/5.x/docs/areas.rst

This configuration demonstrates defining multiple distinct documentation areas ('default', 'internal', 'commercial', 'store') with specific routing rules. Each area can have its own path, host, or name patterns for filtering documented routes. This allows for granular control over API documentation.

```yaml
nelmio_api_doc:
    areas:
        default:
            path_patterns: [ ^/api ]
            host_patterns: [ ^api\. ]
        internal:
            path_patterns: [ ^/internal ]
        commercial:
            path_patterns: [ ^/commercial ]
        store:
            # Includes routes with names containing 'store'
            name_patterns: [ store ]
```

--------------------------------

### Model Documentation with Attributes

Source: https://github.com/nelmio/nelmioapidocbundle/blob/5.x/docs/index.rst

Demonstrates how to document API responses and request bodies using OpenAPI attributes and Nelmio's Model class, including customization with serialization groups.

```APIDOC
## Using Nelmio's Model for Responses and Request Bodies

### Description
This section explains how to leverage NelmioApiDocBundle's `#[OAModel]` attribute to define API request and response schemas, including the use of serialization groups to differentiate between scenarios like creation and update.

### Method
N/A (Configuration/Attribute-based)

### Endpoint
N/A (Applies to various endpoints where models are used)

### Parameters
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **UserDto** (object) - User data model for a successful response.

#### Response Example
```json
{
  "id": 1,
  "username": "johndoe",
  "email": "johndoe@example.com"
}
```

## Request Body Documentation

### Description
This shows how to document request bodies, specifying different schemas for creation (e.g., `create` group) versus updates (e.g., `update` group), where certain fields might be optional.

### Method
N/A (Configuration/Attribute-based)

### Endpoint
N/A (Applies to various endpoints where models are used)

### Parameters
N/A

### Request Example
For creation:
```json
{
  "username": "johndoe",
  "email": "johndoe@example.com"
}
```
For update:
```json
{
  "email": "johndoe.updated@example.com"
}
```

### Response
N/A

## Nesting Models and Media Types

### Description
When `#[OAModel]` is used at the root of `#[OAResponse]` or `#[OAParameter]`, it's automatically nested within an `#[OASchema]`. The default media type is `application/json`. To use `#[OAModel]` directly within `#[OASchema]`, `#[OAItems]`, or `#[OAProperty]`, the `$ref` field must be used.

### Method
N/A (Configuration/Attribute-based)

### Endpoint
N/A

### Parameters
N/A

### Request Example
```php
#[OA\Response(
    content: new OA\JsonContent(ref: new Model(type: User::class))
)]
// or
#[OA\Response(
    content: new OA\XmlContent(example: new OA\Schema(
        type: 'object',
        properties: [
            new OA\Property(property: 'foo', ref: new Model(type: FooClass::class))
        ]
    ))
)]
```

### Response
N/A

## Customizing Symfony Form Type Documentation

### Description
Customize the documentation of a Symfony form field using the `documentation` option within the form builder. This allows specifying details like `type` and `description` that will be reflected in the API documentation.

### Method
N/A (Configuration/Attribute-based)

### Endpoint
N/A

### Parameters
N/A

### Request Example
```php
$builder->add('username', TextType::class, [
    'documentation' => [
        'type' => 'string',
        'description' => 'Your username.',
    ],
]);
```

### Response
N/A

## General PHP Object Documentation (PropertyInfo & JMS Serializer)

### Description
NelmioApiDocBundle uses the Symfony PropertyInfo component by default to describe models. It supports doctrine attributes, type hints, and PHP doc blocks. If the JMS Serializer is used, its metadata is leveraged, and PHP doc blocks provide additional info. Serialization groups with JMS can lead to distinct component schemas.

### Method
N/A (Configuration/Attribute-based)

### Endpoint
N/A

### Parameters
N/A

### Request Example
Example demonstrating JMS serialization groups potentially creating separate schemas:
```php
/**
 * A nested serializer property with no context group
 *
 * @JMS\VirtualProperty
 * @JMS\Type('ArrayCollection<App\Response\ItemResponse>')
 * @JMS\Since('1.0')
 *
 * @return Collection|ItemResponse[]
 */
public function getItems(): Collection|array
{
    return $this->items;
}
```
```yaml
# Configuration to disable JMS serializer usage per endpoint
nelmio_api_doc:
    models: { use_jms: false } # Globally disable
# or per endpoint
#[OA\Response(response: 200, content: new Model(type: UserDto::class, serializationContext: ['useJms' => false]))]
```

### Response
N/A

## Customizing Object Property Documentation with #[OA\Property]

### Description
Customize the documentation of an object's property directly using the `#[OAProperty]` attribute to specify details like descriptions, types, and maximum lengths.

### Method
N/A (Configuration/Attribute-based)

### Endpoint
N/A

### Parameters
N/A

### Request Example
```php
use Nelmio\ApiDocBundle\Attribute\Model;
use OpenApi\Attributes as OA;

class User
{
    /**
     * @var int
     */
    #[OA\Property(description: 'The unique identifier of the user.')]
    public $id;

    #[OA\Property(type: 'string', maxLength: 255)]
    public $username;

    #[OA\Property(ref: new Model(type: User::class))]
    public $friend;
}
```

### Response
N/A
```

--------------------------------

### Dump and Debug Configuration Reference (Terminal)

Source: https://github.com/nelmio/nelmioapidocbundle/blob/5.x/docs/configuration_reference.rst

Commands to display default configuration values and actual configuration used by the application.

```terminal
# displays the default config values
$ php bin/console config:dump-reference nelmio_api_doc

# displays the actual config values used by your application
$ php bin/console debug:config nelmio_api_doc
```