From b504ab2c0942068aa88c819b8f4cbec65e2cdfca Mon Sep 17 00:00:00 2001 From: Vincent Amstoutz Date: Tue, 22 Oct 2024 12:05:32 +0200 Subject: [PATCH] docs: include Laravel for config reference --- core/configuration.md | 440 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 434 insertions(+), 6 deletions(-) diff --git a/core/configuration.md b/core/configuration.md index cb8f843e3c9..87d41710d4c 100644 --- a/core/configuration.md +++ b/core/configuration.md @@ -1,6 +1,8 @@ # Configuration -Here's the complete configuration of the Symfony bundle including default values: +## Symfony configuration + +Here's the complete configuration of the [Symfony variant](/symfony/index.md) including default values: ```yaml # api/config/packages/api_platform.yaml @@ -133,22 +135,22 @@ api_platform: scopes: [] graphql: - # Enabled by default with installed webonyx/graphql-php. + # Enabled by default with installed api-platform/graphql. enabled: false # The default IDE (graphiql or graphql-playground) used when going to the GraphQL endpoint. False to disable. default_ide: 'graphiql' graphiql: - # Enabled by default with installed webonyx/graphql-php and Twig. + # Enabled by default with installed api-platform/graphql and Twig. enabled: false graphql_playground: - # Enabled by default with installed webonyx/graphql-php and Twig. + # Enabled by default with installed api-platform/graphql and Twig. enabled: false introspection: - # Enabled by default with installed webonyx/graphql-php. + # Enabled by default with installed api-platform/graphql. enabled: true # The nesting separator used in the filter names. @@ -278,7 +280,7 @@ api_platform: # ... ``` -## Global Resources Defaults +### Global Resources Defaults for Symfony If you need to globally configure all the resources instead of adding configuration in each one, it's possible to do so with the `defaults` key: @@ -376,3 +378,429 @@ api_platform: # ... ``` + +## Larvel configuration + +Here's the complete configuration of the [Laravel variant](/laravel/index.md) including default values: + +```php + 'API title', + + // The description of the API. + 'description' => 'API description', + + // The version of the API. + 'version' => '0.0.0', + + // Set this to false if you want Webby to disappear. + 'show_webby' => true, + + // Specify a name converter to use. + 'name_converter' => null, + + // Specify an asset package name to use. + 'asset_package' => null, + + // Specify a path name generator to use. + 'path_segment_name_generator' => 'api_platform.path_segment_name_generator.underscore', + + 'validator' => [ + // Enable the serialization of payload fields when a validation error is thrown. + // If you want to serialize only some payload fields, define them like this: [ severity, anotherPayloadField ] + 'serialize_payload_fields' => [], + + // To enable or disable query parameters validation on collection GET requests + 'query_parameter_validation' => true, + ], + + 'eager_loading' => [ + // To enable or disable eager loading. + 'enabled' => true, + + // Fetch only partial data according to serialization groups. + // If enabled, Doctrine ORM entities will not work as expected if any of the other fields are used. + 'fetch_partial' => false, + + // Max number of joined relations before EagerLoading throws a RuntimeException. + 'max_joins' => 30, + + // Force join on every relation. + // If disabled, it will only join relations having the EAGER fetch mode. + 'force_eager' => true, + ], + + // Enable the Swagger documentation and export. + 'enable_swagger' => true, + + // Enable Swagger UI. + 'enable_swagger_ui' => true, + + // Enable ReDoc. + 'enable_re_doc' => true, + + // Enable the entrypoint. + 'enable_entrypoint' => true, + + // Enable the docs. + 'enable_docs' => true, + + // Enable the data collector and the WebProfilerBundle integration. + 'enable_profiler' => true, + + 'collection' => [ + // The name of the query parameter to filter nullable results (with the ExistsFilter). + 'exists_parameter_name' => 'exists', + + // The default order of results. + 'order' => 'ASC', + + // The name of the query parameter to order results (with the OrderFilter). + 'order_parameter_name' => 'order', + + 'pagination' => [ + // The default name of the parameter handling the page number. + 'page_parameter_name' => 'page', + + // The name of the query parameter to enable or disable pagination. + 'enabled_parameter_name' => 'pagination', + + // The name of the query parameter to set the number of items per page. + 'items_per_page_parameter_name' => 'itemsPerPage', + + // The name of the query parameter to enable or disable the partial pagination. + 'partial_parameter_name' => 'partial', + ], + ], + + 'mapping' => [ + // The list of paths with files or directories where the bundle will look for additional resource files. + 'paths' => [], + ], + + // The list of your resources class directories. Defaults to the directories of the mapping paths but might differ. + 'resource_class_directories' => [ + '%kernel.project_dir%/src/Entity', + ], + + 'doctrine' => [ + // To enable or disable Doctrine ORM support. + 'enabled' => true, + ], + + 'doctrine_mongodb_odm' => [ + // To enable or disable Doctrine MongoDB ODM support. + 'enabled' => false, + ], + + 'oauth' => [ + // To enable or disable OAuth. + 'enabled' => false, + + // The OAuth client ID. + 'clientId' => '', + + // The OAuth client secret. + 'clientSecret' => '', + + // The OAuth type. + 'type' => 'oauth2', + + // The OAuth flow grant type. + 'flow' => 'application', + + // The OAuth token URL. Make sure to check the specification tokenUrl is not needed for an implicit flow. + 'tokenUrl' => '', + + // The OAuth authentication URL. + 'authorizationUrl' => '', + + // The OAuth scopes. + 'scopes' => [], + ], + + 'graphql' => [ + // Enabled by default with installed api-platform/graphql. + 'enabled' => false, + + // The default IDE (graphiql or graphql-playground) used when going to the GraphQL endpoint. False to disable. + 'default_ide' => 'graphiql', + + 'graphiql' => [ + // Enabled by default with installed api-platform/graphql. + 'enabled' => false, + ], + + 'introspection' => [ + // Enabled by default with installed api-platform/graphql. + 'enabled' => true, + ], + + // The nesting separator used in the filter names. + 'nesting_separator' => '_', + + 'collection' => [ + 'pagination' => [ + 'enabled' => true, + ], + ], + ], + + 'swagger' => [ + // The active versions of OpenAPI to be exported or used in the swagger_ui. The first value is the default. + 'versions' => [2, 3], + + // The swagger API keys. + 'api_keys' => [], + + 'swagger_ui_extra_configuration' => [ + // Controls the default expansion setting for the operations and tags. It can be 'list' (expands only the tags), 'full' (expands the tags and operations) or 'none' (expands nothing). + 'docExpansion' => 'list', + + // If set, enables filtering. The top bar will show an edit box that you can use to filter the tagged operations that are shown. + 'filter' => false, + + // You can use any other configuration parameters too. + ], + ], + + 'openapi' => [ + // The contact information for the exposed API. + 'contact' => [ + // The identifying name of the contact person/organization. + 'name' => null, + + // The URL pointing to the contact information. MUST be in the format of a URL. + 'url' => null, + + // The email address of the contact person/organization. MUST be in the format of an email address. + 'email' => null, + ], + + // A URL to the Terms of Service for the API. MUST be in the format of a URL. + 'termsOfService' => null, + + // The license information for the exposed API. + 'license' => [ + // The license name used for the API. + 'name' => null, + + // URL to the license used for the API. MUST be in the format of a URL. + 'url' => null, + ], + ], + + 'http_cache' => [ + // To make all responses public by default. + 'public' => null, + + 'invalidation' => [ + // To enable the tags-based cache invalidation system. + 'enabled' => false, + + // URLs of the Varnish servers to purge using cache tags when a resource is updated. + 'varnish_urls' => [], + + // To pass options to the client charged with the request. + 'request_options' => [], + + // Use another service as the purger for example "api_platform.http_cache.purger.varnish.xkey" + 'purger' => 'api_platform.http_cache.purger.varnish.ban', + ], + ], + + 'mercure' => [ + // Enabled by default with installed symfony/mercure-bundle. + 'enabled' => false, + + // The URL sent in the Link HTTP header. If not set, will default to MercureBundle's default hub URL. + 'hub_url' => null, + ], + + 'messenger' => [ + // Enabled by default with installed symfony/messenger and not installed symfony/symfony. + 'enabled' => false, + ], + + 'elasticsearch' => [ + // To enable or disable Elasticsearch support. + 'enabled' => false, + + // The hosts to the Elasticsearch nodes. + 'hosts' => [], + + // The mapping between resource classes and indexes. + 'mapping' => [], + ], + + // The list of exceptions mapped to their HTTP status code. + 'exception_to_status' => [ + AuthenticationException::class => 401, + AuthorizationException::class => 403 + ], + + // The list of routes. + 'routes' => [ + // Global middleware applied to every API Platform routes + // 'middleware' => [] + ], + + // The list of resources. + 'resources' => [ + app_path('Models'), + ], + + // The list of enabled patch formats. The first one will be the default. + 'formats' => [ + 'jsonld' => ['mime_types' => ['application/ld+json']], + 'json' => ['mime_types' => ['application/json']], + 'html' => ['mime_types' => ['text/html']], + ], + + // The list of enabled patch formats. The first one will be the default. + 'patch_formats' => [ + 'json' => ['application/merge-patch+json'], + ], + + // The list of enabled docs formats. The first one will be the default. + 'docs_formats' => [ + 'jsonld' => ['application/ld+json'], + //'jsonapi' => ['application/vnd.api+json'], + 'jsonopenapi' => ['application/vnd.openapi+json'], + 'html' => ['text/html'], + ], + + // The list of enabled error formats. The first one will be the default. + 'error_formats' => [ + 'jsonproblem' => ['mime_types' => ['application/problem+json']], + ], + + // Global resources defaults, see in the next section. + 'defaults' => [ + 'pagination_enabled' => true, + 'pagination_partial' => false, + 'pagination_client_enabled' => false, + 'pagination_client_items_per_page' => false, + 'pagination_client_partial' => false, + 'pagination_items_per_page' => 30, + 'pagination_maximum_items_per_page' => 30, + 'route_prefix' => '/api', + 'middleware' => [], + ], +]; +``` + +### Global Resources Defaults for Laravel + +If you need to globally configure all the resources instead of adding configuration in each one, it's possible to do so with the `defaults` key: + +```php + [ + 'description' => null, + 'iri' => null, + 'short_name' => null, + 'item_operations' => null, + 'collection_operations' => null, + + 'graphql' => null, + + 'elasticsearch' => null, + + 'security' => null, + 'security_message' => null, + 'security_post_denormalize' => null, + 'security_post_denormalize_message' => null, + + 'cache_headers' => [ + // Automatically generate etags for API responses. + 'etag' => true, + + // Default value for the response max age. + 'max_age' => 3600, + + // Default value for the response shared (proxy) max age. + 'shared_max_age' => 3600, + + // Default values of the "Vary" HTTP header. + 'vary' => ['Accept'], + + 'invalidation' => [ + 'xkey' => [ + 'glue' => ' ', + ], + ], + ], + + 'normalization_context' => [ + // Default value to omit null values in conformance with the JSON Merge Patch RFC. + 'skip_null_values' => true, + ], + + 'denormalization_context' => null, + 'swagger_context' => null, + 'openapi_context' => null, + 'deprecation_reason' => null, + 'fetch_partial' => null, + 'force_eager' => null, + 'formats' => null, + 'filters' => null, + 'hydra_context' => null, + 'mercure' => null, + 'messenger' => null, + 'order' => null, + + // To enable or disable pagination for all resource collections. + 'pagination_enabled' => true, + + // To allow the client to enable or disable the pagination. + 'pagination_client_enabled' => false, + + // To allow the client to set the number of items per page. + 'pagination_client_items_per_page' => false, + + // To allow the client to enable or disable the partial pagination. + 'pagination_client_partial' => false, + + // The default number of items per page. + 'pagination_items_per_page' => 30, + + // The maximum number of items per page. + 'pagination_maximum_items_per_page' => null, + + // To allow partial pagination for all resource collections. + // This improves performances by skipping the `COUNT` query. + 'pagination_partial' => false, + + // To use cursor-based pagination. + 'pagination_via_cursor' => null, + + 'pagination_fetch_join_collection' => null, + + 'route_prefix' => null, + 'validation_groups' => null, + 'sunset' => null, + 'input' => null, + 'output' => null, + 'stateless' => null, + + // The URL generation strategy to use for IRIs + 'url_generation_strategy' => UrlGeneratorInterface::ABS_PATH, + + // To enable collecting denormalization errors + 'collectDenormalizationErrors' => false, + ], +]; +```