From 7cddb84b214a18860dcbac6caa9e260e9f48efa1 Mon Sep 17 00:00:00 2001 From: Juan Calderon-Perez <835733+gaby@users.noreply.github.com> Date: Wed, 13 Nov 2024 07:11:09 -0500 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9A=20Doc:=20Update=20intro=20document?= =?UTF-8?q?ation=20(#3204)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Auto update intro documentation --- docs/intro.md | 63 ++++++++++++++++++++++++++++----------------------- 1 file changed, 35 insertions(+), 28 deletions(-) diff --git a/docs/intro.md b/docs/intro.md index 7e0e1798c9..4dc763df36 100644 --- a/docs/intro.md +++ b/docs/intro.md @@ -4,15 +4,15 @@ id: welcome title: 👋 Welcome sidebar_position: 1 --- -An online API documentation with examples so you can start building web apps with Fiber right away! +Welcome to the online API documentation for Fiber, complete with examples to help you start building web applications with Fiber right away! -**Fiber** is an [Express](https://github.com/expressjs/express) inspired **web framework** built on top of [Fasthttp](https://github.com/valyala/fasthttp), the **fastest** HTTP engine for [Go](https://go.dev/doc/). Designed to **ease** things up for **fast** development with **zero memory allocation** and **performance** in mind. +**Fiber** is an [Express](https://github.com/expressjs/express)-inspired **web framework** built on top of [Fasthttp](https://github.com/valyala/fasthttp), the **fastest** HTTP engine for [Go](https://go.dev/doc/). It is designed to facilitate rapid development with **zero memory allocations** and a strong focus on **performance**. -These docs are for **Fiber v3**, which was released on **March XX, 2024**. +These docs are for **Fiber v3**, which was released on **Month xx, 202x**. ### Installation -First of all, [download](https://go.dev/dl/) and install Go. `1.22` or higher is required. +First, [download](https://go.dev/dl/) and install Go. Version `1.22` or higher is required. Installation is done using the [`go get`](https://pkg.go.dev/cmd/go/#hdr-Add_dependencies_to_current_module_and_install_them) command: @@ -22,7 +22,7 @@ go get github.com/gofiber/fiber/v3 ### Zero Allocation -Fiber is optimized for **high-performance**, meaning values returned from **fiber.Ctx** are **not** immutable by default and **will** be re-used across requests. As a rule of thumb, you **must** only use context values within the handler and **must not** keep any references. Once you return from the handler, any values obtained from the context will be re-used in future requests. Here is an example: +Fiber is optimized for **high performance**, meaning values returned from **fiber.Ctx** are **not** immutable by default and **will** be reused across requests. As a rule of thumb, you **must** only use context values within the handler and **must not** keep any references. Once you return from the handler, any values obtained from the context will be reused in future requests. Here is an example: ```go func handler(c fiber.Ctx) error { @@ -44,13 +44,13 @@ func handler(c fiber.Ctx) error { buffer := make([]byte, len(result)) copy(buffer, result) resultCopy := string(buffer) - // Variable is now valid forever + // Variable is now valid indefinitely // ... } ``` -We created a custom `CopyString` function that does the above and is available under [gofiber/utils](https://github.com/gofiber/utils). +We created a custom `CopyString` function that performs the above and is available under [gofiber/utils](https://github.com/gofiber/utils). ```go app.Get("/:foo", func(c fiber.Ctx) error { @@ -61,7 +61,7 @@ app.Get("/:foo", func(c fiber.Ctx) error { }) ``` -Alternatively, you can also use the `Immutable` setting. It will make all values returned from the context immutable, allowing you to persist them anywhere. Of course, this comes at the cost of performance. +Alternatively, you can enable the `Immutable` setting. This makes all values returned from the context immutable, allowing you to persist them anywhere. Note that this comes at the cost of performance. ```go app := fiber.New(fiber.Config{ @@ -69,11 +69,11 @@ app := fiber.New(fiber.Config{ }) ``` -For more information, please check [**\#426**](https://github.com/gofiber/fiber/issues/426), [**\#185**](https://github.com/gofiber/fiber/issues/185) and [**\#3012**](https://github.com/gofiber/fiber/issues/3012). +For more information, please refer to [#426](https://github.com/gofiber/fiber/issues/426), [#185](https://github.com/gofiber/fiber/issues/185), and [#3012](https://github.com/gofiber/fiber/issues/3012). ### Hello, World -Embedded below is essentially the most straightforward **Fiber** app you can create: +Below is the most straightforward **Fiber** application you can create: ```go package main @@ -95,15 +95,15 @@ func main() { go run server.go ``` -Browse to `http://localhost:3000` and you should see `Hello, World!` on the page. +Browse to `http://localhost:3000` and you should see `Hello, World!` displayed on the page. -### Basic routing +### Basic Routing -Routing refers to determining how an application responds to a client request to a particular endpoint, which is a URI (or path) and a specific HTTP request method (`GET`, `PUT`, `POST`, etc.). +Routing determines how an application responds to a client request to a particular endpoint, which is a URI (or path) and a specific HTTP request method (`GET`, `PUT`, `POST`, etc.). Each route can have **multiple handler functions** that are executed when the route is matched. -Route definition takes the following structures: +Route definitions follow the structure below: ```go // Function signature @@ -115,10 +115,10 @@ app.Method(path string, ...func(fiber.Ctx) error) - `path` is a virtual path on the server - `func(fiber.Ctx) error` is a callback function containing the [Context](https://docs.gofiber.io/api/ctx) executed when the route is matched -#### Simple route +#### Simple Route ```go -// Respond with "Hello, World!" on root path, "/" +// Respond with "Hello, World!" on root path "/" app.Get("/", func(c fiber.Ctx) error { return c.SendString("Hello, World!") }) @@ -131,11 +131,11 @@ app.Get("/", func(c fiber.Ctx) error { app.Get("/:value", func(c fiber.Ctx) error { return c.SendString("value: " + c.Params("value")) - // => Get request with value: hello world + // => Response: "value: hello world" }) ``` -#### Optional parameter +#### Optional Parameter ```go // GET http://localhost:3000/john @@ -143,9 +143,10 @@ app.Get("/:value", func(c fiber.Ctx) error { app.Get("/:name?", func(c fiber.Ctx) error { if c.Params("name") != "" { return c.SendString("Hello " + c.Params("name")) - // => Hello john + // => Response: "Hello john" } return c.SendString("Where is john?") + // => Response: "Where is john?" }) ``` @@ -156,27 +157,33 @@ app.Get("/:name?", func(c fiber.Ctx) error { app.Get("/api/*", func(c fiber.Ctx) error { return c.SendString("API path: " + c.Params("*")) - // => API path: user/john + // => Response: "API path: user/john" }) ``` -### Static files +### Static Files -To serve static files such as **images**, **CSS**, and **JavaScript** files, replace your function handler with a file or directory string. -You can check out [static middleware](./middleware/static.md) for more information. -Function signature: +To serve static files such as **images**, **CSS**, and **JavaScript** files, use the `Static` method with a directory path. For more information, refer to the [static middleware](./middleware/static.md). Use the following code to serve files in a directory named `./public`: ```go -app := fiber.New() +package main + +import ( + "github.com/gofiber/fiber/v3" +) -app.Get("/*", static.New("./public")) +func main() { + app := fiber.New() -app.Listen(":3000") + app.Static("/", "./public") + + app.Listen(":3000") +} ``` -Now, you can load the files that are in the `./public` directory: +Now, you can access the files in the `./public` directory via your browser: ```bash http://localhost:3000/hello.html