feat: add URL generation strategy documentation (#1377)

Author: alanpoulain

core/configuration.md

@@ -407,8 +407,7 @@ api_platform:
         stateless: ~
 
         # The URL generation strategy to use for IRIs
-        # Use values from UrlGeneratorInterface
-        url_generation_strategy: ~
+        url_generation_strategy: !php/const ApiPlatform\Core\Api\UrlGeneratorInterface::ABS_PATH
 
         # ...
 ```

core/url-generation-strategy.md

@@ -0,0 +1,92 @@
+# URL Generation Strategy
+
+By default, API Platform generates all URLs as absolute paths to the base URL.
+
+For instance, in JSON-LD, you will get a collection like this:
+
+```json
+{
+  "@context": "/contexts/Book",
+  "@id": "/books",
+  "@type": "hydra:Collection",
+  "hydra:member": [
+    {
+      "@id": "/books/1",
+      "@type": "http://schema.org/Book",
+      "name": "My awesome book"
+    }
+  ],
+  "hydra:totalItems": 1
+}
+```
+
+You may want to use absolute URLs (for instance if resources are used in another API) or network paths instead.
+
+It can be configured globally:
+
+```yaml
+# api/config/packages/api_platform.yaml
+api_platform:
+    defaults:
+        url_generation_strategy: !php/const ApiPlatform\Core\Api\UrlGeneratorInterface::ABS_URL
+```
+
+It can also be configured only for a specific resource:
+
+[codeSelector]
+
+```php
+<?php
+// api/src/Entity/Book.php
+
+use ApiPlatform\Core\Annotation\ApiResource;
+use ApiPlatform\Core\Api\UrlGeneratorInterface;
+
+#[ApiResource(urlGenerationStrategy: UrlGeneratorInterface::ABS_URL)]
+class Book
+{
+    // ...
+}
+```
+
+```yaml
+# api/config/api_platform/resources.yaml
+App\Entity\Book:
+    attributes:
+        url_generation_strategy: !php/const ApiPlatform\Core\Api\UrlGeneratorInterface::ABS_URL
+```
+
+```xml
+<?xml version="1.0" encoding="UTF-8" ?>
+<!-- api/config/api_platform/resources.xml -->
+
+<resources
+        xmlns="https://api-platform.com/schema/metadata"
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xsi:schemaLocation="https://api-platform.com/schema/metadata
+        https://api-platform.com/schema/metadata/metadata-2.0.xsd">
+    <resource class="App\Entity\Book">
+        <attribute name="url_generation_strategy" type="constant">ApiPlatform\Core\Api\UrlGeneratorInterface::ABS_URL</attribute>
+    </resource>
+</resources>
+```
+
+[/codeSelector]
+
+For the above configuration, the collection will be like this:
+
+```json
+{
+  "@context": "http://example.com/contexts/Book",
+  "@id": "http://example.com/books",
+  "@type": "hydra:Collection",
+  "hydra:member": [
+    {
+      "@id": "http://example.com/books/1",
+      "@type": "http://schema.org/Book",
+      "name": "My awesome book"
+    }
+  ],
+  "hydra:totalItems": 1
+}
+```

outline.yaml

@@ -37,6 +37,7 @@ chapters:
       - errors
       - external-vocabularies
       - operation-path-naming
+      - url-generation-strategy
       - extending-jsonld-context
       - identifiers
       - mongodb