From f9ceeafcbd74cbe5f92f3e939ae76db2aa58888b Mon Sep 17 00:00:00 2001
From: Pablo Margreff <pmargreff@gmail.com>
Date: Tue, 31 Oct 2023 07:36:54 -0300
Subject: [PATCH] docs: add routing cheatsheet (#5605)

---
 guides/cheatsheets/router.cheatmd | 83 +++++++++++++++++++++++++++++++
 mix.exs                           |  2 +
 2 files changed, 85 insertions(+)
 create mode 100644 guides/cheatsheets/router.cheatmd

diff --git a/guides/cheatsheets/router.cheatmd b/guides/cheatsheets/router.cheatmd
new file mode 100644
index 0000000000..1f0af13e72
--- /dev/null
+++ b/guides/cheatsheets/router.cheatmd
@@ -0,0 +1,83 @@
+# Routing cheatsheet
+
+> Those need to be declared in the correct router module and scope.
+
+A quick reference to the common routing features' syntax. For an exhaustive overview, refer to the [routing guides](routing.md).
+
+## Routing declaration
+{: .col-2}
+
+### Single route
+
+```elixir
+get "/users", UserController, :index
+patch "/users/:id", UserController, :update
+```
+```elixir
+# generated routes
+~p"/users"
+~p"/users/9" # user_id is 9
+```
+Also accepts `put`, `patch`, `options`, `delete` and `head`.
+
+### Resources
+
+#### Simple
+
+```elixir
+resources "/users", UserController
+```
+Generates `:index`, `:edit`, `:new`, `:show`, `:create`, `:update` and `:delete`.
+
+#### Options
+
+```elixir
+resources "/users", UserController, only: [:show]
+resources "/users", UserController, except: [:create, :delete]
+resources "/users", UserController, as: :person # ~p"/person"
+```
+
+#### Nested
+
+```elixir
+resources "/users", UserController do
+  resources "/posts", PostController
+end
+```
+```elixir
+# generated routes
+~p"/users/3/posts" # user_id is 3
+~p"/users/3/posts/17" # user_id is 3 and post_id = 17
+```
+For more info check the [resources docs.](routing-1.html#resources)
+
+### Scopes
+
+#### Simple
+```elixir
+scope "/admin", HelloWeb.Admin do
+  pipe_through :browser
+
+  resources "/users",   UserController
+end
+```
+```elixir
+# generated path helpers
+~p"/admin/users"
+```
+
+#### Nested
+```elixir
+scope "/api", HelloWeb.Api, as: :api do
+  pipe_through :api
+
+  scope "/v1", V1, as: :v1 do
+    resources "/users", UserController
+  end
+end
+```
+```elixir
+# generated path helpers
+~p"/api/v1/users"
+```
+For more info check the [scoped routes](routing.md#scoped-routes) docs.
diff --git a/mix.exs b/mix.exs
index d6d7e0b52d..85b5e46627 100644
--- a/mix.exs
+++ b/mix.exs
@@ -172,6 +172,7 @@ defmodule Phoenix.MixProject do
       "guides/howto/file_uploads.md",
       "guides/howto/using_ssl.md",
       "guides/howto/writing_a_channels_client.md",
+      "guides/cheatsheets/router.cheatmd",
       "CHANGELOG.md"
     ]
   end
@@ -184,6 +185,7 @@ defmodule Phoenix.MixProject do
       "Real-time": ~r/guides\/real_time\/.?/,
       Testing: ~r/guides\/testing\/.?/,
       Deployment: ~r/guides\/deployment\/.?/,
+      Cheatsheets: ~r/guides\/cheatsheets\/.?/,
       "How-to's": ~r/guides\/howto\/.?/
     ]
   end