From dded14e8309282b0056fe175a2b3b44b1c094f1f Mon Sep 17 00:00:00 2001 From: djordy Date: Sun, 19 Jan 2025 14:44:15 +0100 Subject: [PATCH 1/3] Add Configuration Reference --- docs/configuration_reference.rst | 80 ++++++++++++++++++++++++++++++++ 1 file changed, 80 insertions(+) create mode 100644 docs/configuration_reference.rst diff --git a/docs/configuration_reference.rst b/docs/configuration_reference.rst new file mode 100644 index 000000000..d06507de2 --- /dev/null +++ b/docs/configuration_reference.rst @@ -0,0 +1,80 @@ +Configuration Reference +============= + +The bundle configuration is stored under the ``nelmio_api_doc`` key in your application configuration. + + .. code-block:: 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 + + .. code-block:: yaml + + # Example default configuration + 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 + 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: [] + # 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 + # 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: [] From a94dfffd31177ed9ff0d10ad5b9d0a9302f4a312 Mon Sep 17 00:00:00 2001 From: djordy Date: Sun, 19 Jan 2025 15:35:30 +0100 Subject: [PATCH 2/3] Add Configuration Reference --- docs/configuration_reference.rst | 290 +++++++++++++++++++++++++++---- docs/index.rst | 1 + 2 files changed, 256 insertions(+), 35 deletions(-) diff --git a/docs/configuration_reference.rst b/docs/configuration_reference.rst index d06507de2..321ac3e63 100644 --- a/docs/configuration_reference.rst +++ b/docs/configuration_reference.rst @@ -1,46 +1,182 @@ Configuration Reference -============= +======================= The bundle configuration is stored under the ``nelmio_api_doc`` key in your application configuration. - .. code-block:: terminal +.. code-block:: terminal - # displays the default config values - $ php bin/console config:dump-reference nelmio_api_doc + # 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 + # displays the actual config values used by your application + $ php bin/console debug:config nelmio_api_doc - .. code-block:: yaml +.. code-block:: yaml - # Example default configuration - 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 - cache: - # define cache pool to use - pool: null - # define cache item id - item_id: null - # The documentation to use as base + # Example default configuration + 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 + 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: [] + # 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_annotation: false + # 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' - # List of enabled Media Types - media_types: - - json - # UI configuration options + 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: [] + +Configuration +------------- + +type_info +~~~~~~~~~ + +**type**: ``boolean`` +**default**: ``false`` + +Whether to use `symfony/type-info`_ for determining types. + +.. tip:: + + If you are using Symfony 7.2 or higher, you should set this option to ``true``. As this greatly improves type detection. + +use_validation_groups +~~~~~~~~~~~~~~~~~~~~~ + +**type**: ``boolean`` +**default**: ``false`` + +If true, ``groups`` passed to ``#[Model]`` attributes will be used to limit validation constraints. + +cache +~~~~~ + +**type**: ``dictionary`` +**allowed keys**: ``pool``, ``item_id`` + +Cache configuration for the generated documentation. + +.. code-block:: yaml + nelmio_api_doc: + # ... + + cache: + # define cache pool to use + pool: 'cache.app' + # define cache item id + item_id: 'nelmio_api_doc_cache' + +documentation +~~~~~~~~~~~~~ + +**type**: ``dictionary`` + +The api documentation to use as base. + +.. code-block:: yaml + nelmio_api_doc: + # ... + + documentation: + # Any valid OpenAPI/Swagger documentation + info: + title: 'My App' + description: 'My App Description' + +media_types +~~~~~~~~~~~ + +**type**: ``list`` +**default**: ``['json']`` +**allowed values**: ``json``, ``xml`` + +List of enabled Media Types. + +html_config +~~~~~~~~~~~ + +**type**: ``dictionary`` +**default**: ``[]`` +**allowed keys**: ``assets_mode``, ``swagger_ui_config``, ``redocly_config`` + +UI configuration options. + +.. code-block:: yaml + nelmio_api_doc: + # ... + html_config: - assets_mode: cdn + 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: [] - # Filter the routes that are documented + +areas +~~~~~ + +**type**: ``dictionary`` + +Filter the routes that are documented. + +.. code-block:: yaml + nelmio_api_doc: + # ... + areas: default: path_patterns: @@ -53,11 +189,8 @@ The bundle configuration is stored under the ``nelmio_api_doc`` key in your appl name_patterns: # Example: # - ^api_v1 - # whether to filter by attributes - with_attribute: false - # if set disables default routes without attributes + with_annotation: false disable_default_routes: false - # The base documentation used for the area documentation: # Example: # info: @@ -68,13 +201,100 @@ The bundle configuration is stored under the ``nelmio_api_doc`` key in your appl pool: null # define cache item id for the area item_id: null + +path_patterns +............. + +**type**: ``list`` +**default**: ``[]`` + +List of regular expressions to match against the path of the route. + +host_patterns +............. + +**type**: ``list`` +**default**: ``[]`` + +List of regular expressions to match against the host of the route. + +name_patterns +............. + +**type**: ``list`` +**default**: ``[]`` + +List of regular expressions to match against the name of the route. + +with_annotation +............... + +**type**: ``boolean`` +**default**: ``false`` + +Whether to only document routes with the ``#[Areas]`` annotation/attribute. + +disable_default_routes +...................... + +**type**: ``boolean`` +**default**: ``false`` + +If set, disables default routes without annotations/attributes. + +documentation +............. + +**type**: ``dictionary`` +**default**: ``[]`` + +The base documentation used for the area. + +cache +..... + +**type**: ``dictionary`` +**allowed keys**: ``pool``, ``item_id`` + +Cache configuration for the generated area documentation. + +models +~~~~~~ + +**type**: ``dictionary`` + +Configuration for models. + +use_jms +....... + +**type**: ``boolean`` +**default**: ``false`` + +Whether to use JMS Serializer for serialization. + +names +..... + +**type**: ``list`` + +List of models, this can be used to: +- Define models that are not automatically detected. +- Create a custom alias (schema name) for a model. (based groups/options/serializationContext/areas) + +.. code-block:: yaml + nelmio_api_doc: + # ... + models: use_jms: false names: - - alias: ~ # Example: 'Foo' - type: ~ # Example: 'App\Foo' - groups: null - options: null - serializationContext: [] - areas: [] + # Alias the class 'App\Foo' to 'FooPrivate' for the 'private' group + alias: 'FooPrivate' + type: 'App\Foo' + groups: + - 'private' + + +.. _`symfony/type-info`: https://symfony.com/doc/current/components/type_info.html \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index 9f3e2c381..6ffdc187f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -617,6 +617,7 @@ If you need more complex features, take a look at: commands security symfony_attributes + configuration_reference faq .. _`SwaggerPHP examples`: https://github.com/zircote/swagger-php/tree/master/Examples From 81e052e972b4dd6727f9590c3248bcad7edd1e4c Mon Sep 17 00:00:00 2001 From: djordy Date: Sun, 19 Jan 2025 15:37:22 +0100 Subject: [PATCH 3/3] style fix --- docs/configuration_reference.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/configuration_reference.rst b/docs/configuration_reference.rst index 321ac3e63..bf84c27ad 100644 --- a/docs/configuration_reference.rst +++ b/docs/configuration_reference.rst @@ -111,6 +111,7 @@ cache Cache configuration for the generated documentation. .. code-block:: yaml + nelmio_api_doc: # ... @@ -128,6 +129,7 @@ documentation The api documentation to use as base. .. code-block:: yaml + nelmio_api_doc: # ... @@ -156,6 +158,7 @@ html_config UI configuration options. .. code-block:: yaml + nelmio_api_doc: # ... @@ -174,6 +177,7 @@ areas Filter the routes that are documented. .. code-block:: yaml + nelmio_api_doc: # ... @@ -283,6 +287,7 @@ List of models, this can be used to: - Create a custom alias (schema name) for a model. (based groups/options/serializationContext/areas) .. code-block:: yaml + nelmio_api_doc: # ...