Add docs for api-platform/core#2288

Author: dunglas

core/performance.md

@@ -1,4 +1,4 @@
-# Performance
+# Performance and Cache
 
 ## Enabling the Built-in HTTP Cache Invalidation System
 
@@ -68,6 +68,44 @@ final class UserResourcesSubscriber implements EventSubscriberInterface
 }
 ```
 
+## Setting Custom HTTP Cache Headers
+
+The `cache_headers` attribute can be used to set custom HTTP cache headers:
+
+```php
+use ApiPlatform\Core\Annotation\ApiResource;
+
+/**
+ * @ApiResource(cacheHeaders={"max_age"=60, "shared_max_age"=120})
+ */
+class Book
+{
+    // ...
+}
+```
+
+For all endpoints related to this resource class, the following HTTP header will be set:
+
+`Cache-Controle: max-age=60, public, s-maxage=120`
+
+It's also possible to set different cache headers per operation:
+
+```php
+use ApiPlatform\Core\Annotation\ApiResource;
+
+/**
+ * @ApiResource(
+ *     itemOperations={
+ *         "get"={"cache_headers"={"max_age"=60, "shared_max_age"=120}}
+ *     }
+ * )
+ */
+class Book
+{
+    // ...
+}
+```
+
 ## Enabling the Metadata Cache
 
 Computing metadata used by the bundle is a costly operation. Fortunately, metadata can be computed once and then cached.