diff --git a/README.md b/README.md
index 5d2b0307..4282e2de 100644
--- a/README.md
+++ b/README.md
@@ -110,6 +110,7 @@ This is very similar to how [Plug Router](https://github.com/elixir-plug/plug#th
 - [`Tesla.Middleware.MethodOverride`](https://hexdocs.pm/tesla/Tesla.Middleware.MethodOverride.html) - set X-Http-Method-Override
 - [`Tesla.Middleware.Logger`](https://hexdocs.pm/tesla/Tesla.Middleware.Logger.html) - log requests (method, url, status, time)
 - [`Tesla.Middleware.KeepRequest`](https://hexdocs.pm/tesla/Tesla.Middleware.KeepRequest.html) - keep request body & headers
+- [`Tesla.Middleware.PathParams`](https://hexdocs.pm/tesla/Tesla.Middleware.PathParams.html) - use templated URLs
 
 #### Formats
 - [`Tesla.Middleware.FormUrlencoded`](https://hexdocs.pm/tesla/Tesla.Middleware.FormUrlencoded.html) - urlencode POST body parameter, useful for POSTing a map/keyword list
diff --git a/lib/tesla/middleware/path_params.ex b/lib/tesla/middleware/path_params.ex
index 3432f5f6..5a78db99 100644
--- a/lib/tesla/middleware/path_params.ex
+++ b/lib/tesla/middleware/path_params.ex
@@ -1,8 +1,32 @@
 defmodule Tesla.Middleware.PathParams do
   @behaviour Tesla.Middleware
 
+  @moduledoc """
+  Use templated URLs with separate params.
+
+  Useful when logging or reporting metric per URL.
+
+
+  ### Example usage
+  ```
+  defmodule MyClient do
+    use Tesla
+
+    plug Tesla.Middleware.BaseURl, "https://api.example.com"
+    plug Tesla.Middleware.Logger # or some monitoring middleware
+    plug Tesla.Middleware.PathParams
+
+    def user(id) do
+      params = [id: id]
+      get("/users/:id", opts: [path_params: params])
+    end
+  end
+  ```
+  """
+
   @rx ~r/:([\w_]+)/
 
+  @doc false
   @impl true
   def call(env, next, _) do
     url = build_url(env.url, env.opts[:path_params])