From f3d0c4cbd62aeb0efe7abbfcca73a6f8200813d1 Mon Sep 17 00:00:00 2001
From: Lukas Knuth <lukas@7mind.de>
Date: Thu, 25 May 2023 15:47:25 +0200
Subject: [PATCH] Explained middleware ordering

---
 lib/tesla/middleware.ex | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/lib/tesla/middleware.ex b/lib/tesla/middleware.ex
index e79d9849..660c26ae 100644
--- a/lib/tesla/middleware.ex
+++ b/lib/tesla/middleware.ex
@@ -14,6 +14,15 @@ defmodule Tesla.Middleware do
   or inside tuple in case of dynamic middleware (`Tesla.client/1`):
 
       Tesla.client([{Tesla.Middleware.BaseUrl, "https://example.com"}])
+      
+  ## Ordering
+  
+  The order in which middleware is defined matters. Note that the order when _sending_ the request
+  matches the order the middleware was defined in, but the order when _receiving_ the response
+  is reversed.
+  
+  For example, `Tesla.Middleware.DecompressResponse` must come _after_ `Tesla.Middleware.JSON`,
+  otherwise the response isn't decompressed before it reaches the JSON parser.
 
   ## Writing custom middleware