From 600b3b191f485c9f67ab97416ff174c5a7b0af90 Mon Sep 17 00:00:00 2001
From: David Buchmann <david.buchmann@liip.ch>
Date: Wed, 8 Nov 2023 16:38:06 +0100
Subject: [PATCH] hint for mapping request payload error messages

Co-authored-by: Oskar Stark <oskarstark@googlemail.com>
---
 controller.rst | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/controller.rst b/controller.rst
index 0f2d5b76bac..6837c28c837 100644
--- a/controller.rst
+++ b/controller.rst
@@ -502,6 +502,14 @@ payload formats::
         // ...
     }
 
+.. tip::
+
+    If you build a JSON API, make sure to declare your route as using the JSON
+    :ref:`format <routing-format-parameter>`. This will make the error handling
+    output a JSON response in case of validation errors, rather than an HTML page::
+
+        #[Route('/dashboard', name: 'dashboard', format: 'json')]
+
 Make sure to install `phpstan/phpdoc-parser`_ and `phpdocumentor/type-resolver`_
 if you want to map a nested array of specific DTOs::