Merge pull request #4311 from gofiber/docs/routing-guide-restructure

docs: restructure routing guide and split handler partials

Author: ReneWerner87

docs/api/app.md

@@ -3,58 +3,29 @@ id: app
 title: 🚀 App
 description: The `App` type represents your Fiber application.
 sidebar_position: 2
+toc_max_heading_level: 4
 ---
 
 import Reference from '@site/src/components/reference';
 
-## Helpers
-
-### GetString
-
-Returns `s` unchanged when [`Immutable`](./fiber.md#immutable) is disabled or `s` resides in read-only memory. Otherwise, it returns a detached copy using `strings.Clone`.
-
-```go title="Signature"
-func (app *App) GetString(s string) string
-```
-
-### GetBytes
-
-Returns `b` unchanged when [`Immutable`](./fiber.md#immutable) is disabled or `b` resides in read-only memory. Otherwise, it returns a detached copy.
-
-```go title="Signature"
-func (app *App) GetBytes(b []byte) []byte
-```
-
-### ReloadViews
-
-Reloads the configured view engine on demand by calling its `Load` method. Use this helper in development workflows (e.g., file watchers or debug-only routes) to pick up template changes without restarting the server. Returns an error if no view engine is configured or reloading fails.
-
-```go title="Signature"
-func (app *App) ReloadViews() error
-```
-
-```go title="Example"
-app := fiber.New(fiber.Config{Views: engine})
-
-app.Get("/dev/reload", func(c fiber.Ctx) error {
-    if err := app.ReloadViews(); err != nil {
-        return err
-    }
-    return c.SendString("Templates reloaded")
-})
-```
-
 ## Routing
 
 import RoutingHandler from './../partials/routing/handler.md';
+import RoutingUse from './../partials/routing/use.md';
 
 ### Route Handlers
 
 <RoutingHandler />
 
+Beyond the native `func(fiber.Ctx)` forms, Fiber also adapts Express-style, `net/http`, and `fasthttp` handlers. See [Handler types](../guide/routing.md#handler-types) in the routing guide for the full list of supported shapes.
+
+### Use
+
+<RoutingUse />
+
 ### Mounting
 
-Mount another Fiber instance with [`app.Use`](./app.md#use), similar to Express's [`router.use`](https://expressjs.com/en/api.html#router.use).
+Mount another Fiber instance with [`app.Use`](#use), similar to Express's [`router.use`](https://expressjs.com/en/api.html#router.use).
 
 ```go title="Example"
 package main
@@ -80,17 +51,9 @@ func main() {
 }
 ```
 
-### State / SharedState
-
-`State()` returns in-process state (local to the current process).  
-`SharedState()` returns storage-backed state intended for prefork/multi-process sharing.
-
-```go title="Signature"
-func (app *App) State() *State
-func (app *App) SharedState() *SharedState
-```
-
-See [State Management](./state.md) for usage and examples.
+:::caution
+Unlike Express, Fiber does not strip the mount prefix. Inside the mounted app, `c.Path()` still returns the full request path (`/john/doe`, not `/doe`); there is no `req.baseUrl` equivalent.
+:::
 
 ### MountPath
 
@@ -223,6 +186,7 @@ func main() {
     app.RouteChain("/events").All(func(c fiber.Ctx) error {
         // Runs for all HTTP verbs first
         // Think of it as route-specific middleware!
+        return c.Next()
     }).
     Get(func(c fiber.Ctx) error {
         return c.SendString("GET /events")
@@ -375,6 +339,7 @@ package main
 
 import (
     "encoding/json"
+    "fmt"
     "log"
 
     "github.com/gofiber/fiber/v3"
@@ -660,7 +625,7 @@ func (app *App) Config() Config
 
 ## Handler
 
-`Handler` returns the server handler that can be used to serve custom [`\*fasthttp.RequestCtx`](https://pkg.go.dev/github.com/valyala/fasthttp#RequestCtx) requests.
+`Handler` returns the server handler that can be used to serve custom [`*fasthttp.RequestCtx`](https://pkg.go.dev/github.com/valyala/fasthttp#RequestCtx) requests.
 
 ```go title="Signature"
 func (app *App) Handler() fasthttp.RequestHandler
@@ -798,6 +763,18 @@ Use `SetTLSHandler` to set [`ClientHelloInfo`](https://datatracker.ietf.org/doc/
 func (app *App) SetTLSHandler(tlsHandler *TLSHandler)
 ```
 
+## State / SharedState
+
+`State()` returns in-process state (local to the current process).  
+`SharedState()` returns storage-backed state intended for prefork/multi-process sharing.
+
+```go title="Signature"
+func (app *App) State() *State
+func (app *App) SharedState() *SharedState
+```
+
+See [State Management](./state.md) for usage and examples.
+
 ## Test
 
 Testing your application is done with the `Test` method. Use this method for creating `_test.go` files or when you need to debug your routing logic. The default timeout is `1s`; to disable a timeout altogether, pass a `TestConfig` struct with `Timeout: 0`.
@@ -855,8 +832,7 @@ config := fiber.TestConfig{
 
 :::caution
 
-This is **not** the same as supplying an empty `TestConfig{}` to
-`app.Test(), but rather be the equivalent of supplying:
+Calling `app.Test(req)` uses the defaults above. Supplying an empty `fiber.TestConfig{}` instead is **not** equivalent; it is the same as supplying:
 
 ```go title="Empty TestConfig"
 cfg := fiber.TestConfig{
@@ -877,7 +853,11 @@ This would make a Test that has no timeout.
 func (app *App) Hooks() *Hooks
 ```
 
-## RebuildTree
+## Route Management
+
+Routes are normally defined before the app starts. You can also add or remove them at runtime with the methods below, but these operations are **not thread-safe** and are performance-intensive, so use them sparingly and only in development.
+
+### RebuildTree
 
 The `RebuildTree` method is designed to rebuild the route tree and enable dynamic route registration. It returns a pointer to the `App` instance.
 
@@ -887,8 +867,6 @@ func (app *App) RebuildTree() *App
 
 **Note:** Use this method with caution. It is **not** thread-safe and calling it can be very performance-intensive, so it should be used sparingly and only in development mode. Avoid using it concurrently.
 
-### Example Usage
-
 Here’s an example of how to define and register routes dynamically:
 
 ```go title="Example"
@@ -921,7 +899,7 @@ func main() {
 
 In this example, a new route is defined and then `RebuildTree()` is called to ensure the new route is registered and available.
 
-## RemoveRoute
+### RemoveRoute
 
 This method removes a route by path. You must call the `RebuildTree()` method after the removal to finalize the update and rebuild the routing tree.
 If no methods are specified, the route will be removed for all HTTP methods defined in the app. To limit removal to specific methods, provide them as additional arguments.
@@ -969,7 +947,7 @@ func main() {
 }
 ```
 
-## RemoveRouteByName
+### RemoveRouteByName
 
 This method removes a route by name.
 If no methods are specified, the route will be removed for all HTTP methods defined in the app. To limit removal to specific methods, provide them as additional arguments.
@@ -978,11 +956,48 @@ If no methods are specified, the route will be removed for all HTTP methods defi
 func (app *App) RemoveRouteByName(name string, methods ...string)
 ```
 
-## RemoveRouteFunc
+### RemoveRouteFunc
 
 This method removes a route by function having `*Route` parameter.
 If no methods are specified, the route will be removed for all HTTP methods defined in the app. To limit removal to specific methods, provide them as additional arguments.
 
 ```go title="Signature"
 func (app *App) RemoveRouteFunc(matchFunc func(r *Route) bool, methods ...string)
 ```
+
+## Helpers
+
+### GetString
+
+Returns `s` unchanged when [`Immutable`](./fiber.md#immutable) is disabled or `s` resides in read-only memory. Otherwise, it returns a detached copy using `strings.Clone`.
+
+```go title="Signature"
+func (app *App) GetString(s string) string
+```
+
+### GetBytes
+
+Returns `b` unchanged when [`Immutable`](./fiber.md#immutable) is disabled or `b` resides in read-only memory. Otherwise, it returns a detached copy.
+
+```go title="Signature"
+func (app *App) GetBytes(b []byte) []byte
+```
+
+### ReloadViews
+
+Reloads the configured view engine on demand by calling its `Load` method. Use this helper in development workflows (e.g., file watchers or debug-only routes) to pick up template changes without restarting the server. Returns an error if no view engine is configured or reloading fails.
+
+```go title="Signature"
+func (app *App) ReloadViews() error
+```
+
+```go title="Example"
+app := fiber.New(fiber.Config{Views: engine})
+
+app.Get("/dev/reload", func(c fiber.Ctx) error {
+    if err := app.ReloadViews(); err != nil {
+        return err
+    }
+    return c.SendString("Templates reloaded")
+})
+```

docs/guide/grouping.md

@@ -81,3 +81,29 @@ func main() {
     log.Fatal(app.Listen(":3000"))
 }
 ```
+
+## Route
+
+[`Route`](../api/app.md#route) groups routes under a common prefix declared inside a single callback, with an optional name prefix. It is shorthand for nesting with `Group`.
+
+```go
+app.Route("/api/v1", func(r fiber.Router) {
+    r.Get("/users", handler).Name("users")   // /api/v1/users  (name: v1.users)
+    r.Post("/users", handler).Name("create") // /api/v1/users  (name: v1.create)
+}, "v1.")
+```
+
+## RouteChain
+
+When several HTTP methods share the **same path**, [`RouteChain`](../api/app.md#routechain) lets you declare the path once and chain the verb handlers. An `All` in the chain runs before the verb handlers on that path, acting as route-specific middleware.
+
+```go
+app.RouteChain("/events").
+    All(func(c fiber.Ctx) error { return c.Next() }). // route-local middleware
+    Get(func(c fiber.Ctx) error { return c.SendString("GET /events") }).
+    Post(func(c fiber.Ctx) error { return c.SendString("POST /events") })
+```
+
+:::note
+Within a chain, `All` registers prefix-matched middleware (like [`app.Use`](../api/app.md#use)), not the exact-path `App.All`, so it also runs for sub-paths of the chain path.
+:::