docs: ✨ docs: ✨ added routes and controllers docs

Author: MrRevillod

docs/.vitepress/config.mts

@@ -55,7 +55,16 @@ export default defineConfig({
               },
               {
                 text: "Controllers and Routes",
-                link: "/en/key-concepts/controllers-routes",
+                items: [
+                  {
+                    text: "Defining Controllers",
+                    link: "/en/key-concepts/controllers/definition",
+                  },
+                  {
+                    text: "Defining Routes",
+                    link: "/en/key-concepts/controllers/routes",
+                  },
+                ],
               },
               {
                 text: "Context and Request Handling",
@@ -168,8 +177,17 @@ export default defineConfig({
                 ],
               },
               {
-                text: "Controladores y Rutas",
-                link: "/es/key-concepts/controllers-routes",
+                text: "Controladores y rutas",
+                items: [
+                  {
+                    text: "Defición de Controladores",
+                    link: "/es/key-concepts/controllers/definition",
+                  },
+                  {
+                    text: "Implementación de Rutas",
+                    link: "/es/key-concepts/controllers/routes",
+                  },
+                ],
               },
               {
                 text: "Manejo de Contexto y Peticiones",

docs/en/index.md

@@ -0,0 +1,33 @@
+---
+layout: home
+
+hero:
+  name: "Sword"
+  text: "Rust Web Framework"
+  tagline: Asynchronous, modular and ready to scale.
+  image:
+    src: /logo.png
+    alt: Sword Logo
+  actions:
+    - theme: brand
+      text: What is Sword?
+      link: /en/introduction/
+    - theme: alt
+      text: Get Started
+      link: /en/introduction/how-to-start.md
+    - theme: alt
+      text: GitHub
+      link: "https://github.com/sword-web/"
+
+features:
+  - title: Asynchronous by default
+    details:
+      Built on Tokio, Sword is an asynchronous framework that relies on the
+      well-known Tokio runtime to handle multiple concurrent connections efficiently.
+
+  - title: Module-based architecture
+    details: Build server-side applications with a modular architecture, layer separation, and dependency injection.
+
+  - title: Integrated middlewares
+    details: Includes integrated middlewares for CORS, Request Timeout, security headers, and more.
+---

docs/en/key-concepts/configuration/application.md

@@ -62,47 +62,3 @@ database_url = "${DATABASE_URL}"     # Uses DATABASE_URL variable (required)
 ```
 
 The syntax is: `${VARIABLE_NAME:default_value}`. If you don't specify a default value and the variable doesn't exist, configuration loading will fail.
-
-## Configuration Parameters
-
-### `host`
-
-- **Type**: String
-- **Default value**: `"0.0.0.0"`
-- **Description**: IP address or hostname where the server will bind. `0.0.0.0` means it will listen on all available network interfaces.
-
-### `port`
-
-- **Type**: Integer (u16)
-- **Default value**: `8080`
-- **Description**: Port number on which the server will listen for HTTP connections.
-
-### `body_limit`
-
-- **Type**: String
-- **No default value** (required)
-- **Description**: Maximum size allowed for request bodies. Useful for preventing denial-of-service (DoS) attacks. Valid examples: `"1MB"`, `"100KB"`, `"5GB"`.
-
-### `request_timeout_seconds`
-
-- **Type**: Integer (u64)
-- **Default value**: `null` (no timeout)
-- **Description**: Maximum time in seconds to wait for a request. If exceeded, the request will be automatically aborted.
-
-### `graceful_shutdown`
-
-- **Type**: Boolean
-- **Default value**: `false`
-- **Description**: If enabled, the server will allow in-flight requests to complete before shutting down when it receives a termination signal (such as Ctrl+C).
-
-### `name`
-
-- **Type**: String
-- **Default value**: `null` (optional)
-- **Description**: Application name. Displayed in startup logs.
-
-### `environment`
-
-- **Type**: String
-- **Default value**: `null` (optional)
-- **Description**: Environment name (e.g., "development", "production"). You can use this variable in your code to adapt your application's behavior based on the environment.

docs/en/key-concepts/controllers/definition.md

@@ -0,0 +1,39 @@
+# Defining Controllers
+
+A controller is commonly known as a function that handles an HTTP request and returns an HTTP response. In Sword, we handle controllers as `structs`, and their methods are what actually handle the HTTP requests.
+
+You'll notice this is a different approach from other Rust web frameworks, where controllers are functions. This object-oriented approach allows you to group related functionality within the same controller, making it easier to organize and maintain your code.
+
+## Creating a Controller
+
+To define a controller, you need to create a `struct` and mark it using the `#[controller]` macro.
+
+```rust
+use sword::prelude::*;
+
+#[controller("/api")]
+struct ApiController;
+
+// ... assuming main function and other imports ...
+
+Application::builder()
+    .with_controller::<ApiController>()
+    .build()
+```
+
+### `#[controller]` Macro Attributes
+
+#### `path`
+
+The `path` attribute defines the route prefix for all routes within the controller. In the example above, all routes defined in `ApiController` will have the `/api` prefix.
+
+### `version`
+
+The `version` attribute allows you to define a version for the controller, which will be included in the route. For example:
+
+```rust
+#[controller("/api", version = "v1")]
+struct ApiController;
+```
+
+This is equivalent to defining the controller with the `/api/v1` prefix. However, it provides additional semantic meaning, indicating that this controller belongs to version 1 of your API.

docs/en/key-concepts/controllers/routes.md

@@ -0,0 +1,64 @@
+# Defining Routes in Controllers
+
+In Sword, routes are defined within the implementation block of a controller. To do this, you use the `#[routes]` macro above the `impl` block.
+
+```rust
+use sword::prelude::*;
+use serde_json::Value;
+
+#[controller("/api")]
+struct ApiController;
+
+#[routes]
+impl ApiController {
+    #[get("/hello")]
+    async fn hello(&self) -> HttpResponse {
+        HttpResponse::Ok().message("Hello, world!")
+    }
+}
+```
+
+A controller can access the request context through the `ctx: Context` parameter:
+
+```rust
+use sword::prelude::*;
+
+#[controller("/api")]
+struct ApiController;
+
+#[routes]
+impl ApiController {
+    #[get("/hello/{name}")]
+    async fn hello(&self, ctx: Context) -> HttpResult<HttpResponse> {
+        let name: String = ctx.param("name")?;
+
+        Ok(HttpResponse::Ok().message(format!("Hello, {}!", name)))
+    }
+}
+```
+
+To learn about all the features of `Context`, see the [Request Context](../context-requests.md) section.
+
+## Supported HTTP Methods
+
+Currently, Sword supports the most common HTTP methods:
+
+- `#[get("...")]`
+- `#[post("...")]`
+- `#[put("...")]`
+- `#[delete("...")]`
+- `#[patch("...")]`
+
+### Route Syntax
+
+Routes can include parameters, which are defined by enclosing the parameter name in curly braces `{}`. For example, in the route `/users/{id}`, `{id}` is a parameter that can be extracted from the request context.
+
+For more details on route syntax, you can [check the axum documentation](https://docs.rs/axum/latest/axum/routing/struct.Router.html#method.route).
+
+## Using `async`
+
+Sword is built on `axum`, which uses `tokio` as its async runtime. Therefore, all controller methods must be `async`, even if they don't perform any asynchronous operations within the method body.
+
+## Using `&self`
+
+As you may have noticed, controller methods receive `&self` as their first parameter. This allows controllers to inject dependencies through their fields. However, this topic will be covered in detail in the [Dependency Injection](../dependency-injection.md) section.

docs/es/key-concepts/configuration/application.md

@@ -62,47 +62,3 @@ database_url = "${DATABASE_URL}"     # Usa la variable DATABASE_URL (required)
 ```
 
 La sintaxis es: `${VARIABLE_NAME:valor_por_defecto}`. Si no especificas un valor por defecto y la variable no existe, la carga fallará.
-
-## Parámetros de configuración
-
-### `host`
-
-- **Tipo**: String
-- **Valor por defecto**: `"0.0.0.0"`
-- **Descripción**: Dirección IP o hostname donde se vinculará el servidor. `0.0.0.0` significa que escuchará en todas las interfaces de red disponibles.
-
-### `port`
-
-- **Tipo**: Integer (u16)
-- **Valor por defecto**: `8080`
-- **Descripción**: Puerto en el que escuchará el servidor para conexiones HTTP.
-
-### `body_limit`
-
-- **Tipo**: String
-- **Sin valor por defecto** (requerido)
-- **Descripción**: Tamaño máximo permitido para los cuerpos de las solicitudes. Útil para prevenir ataques de negación de servicio (DoS). Ejemplos válidos: `"1MB"`, `"100KB"`, `"5GB"`.
-
-### `request_timeout_seconds`
-
-- **Tipo**: Integer (u64)
-- **Valor por defecto**: `null` (sin timeout)
-- **Descripción**: Tiempo máximo en segundos que se espera a una solicitud. Si se excede, la solicitud será abortada automáticamente.
-
-### `graceful_shutdown`
-
-- **Tipo**: Boolean
-- **Valor por defecto**: `false`
-- **Descripción**: Si está habilitado, el servidor permitirá que las solicitudes en curso se completen antes de apagarse cuando reciba una señal de terminación (como Ctrl+C).
-
-### `name`
-
-- **Tipo**: String
-- **Valor por defecto**: `null` (opcional)
-- **Descripción**: Nombre de la aplicación. Se muestra en los logs de inicio.
-
-### `environment`
-
-- **Tipo**: String
-- **Valor por defecto**: `null` (opcional)
-- **Descripción**: Nombre del entorno (ej: "development", "production"). Puedes usar esta variable en tu código para adaptar el comportamiento de la aplicación.

docs/es/key-concepts/controllers-routes.md

@@ -0,0 +1,40 @@
+# Definición de Controladores
+
+Un controlador es comunmente conocido como una función que maneja una solicitud HTTP y devuelve una respuesta HTTP. En sword manejamos los controladores como `structs`, sus metodos son los que manejan las solicitudes HTTP.
+
+Notarás que este es un enfoque diferente al de otros frameworks web en Rust, donde los controladores son funciones. Este enfoque orientado a objetos permite agrupar funcionalidades relacionadas dentro de un mismo controlador, facilitando la organización y el mantenimiento del código.
+
+## Definiendo un Controlador
+
+Para definir un controlador, debes crear un `struct` y luego marcarla utilizando la macro `#[controller]`.
+
+```rust
+use sword::prelude::*;
+
+#[controller("/api")]
+struct ApiController;
+
+... asumiendo la función main y otras importaciones ...
+
+Application::builder()
+    .with_controller::<ApiController>()
+    .build()
+
+```
+
+### Atributos de la Macro `#[controller]`
+
+#### `path`
+
+El atributo `path` define el prefijo de ruta para todas las rutas dentro del controlador. En el ejemplo anterior, todas las rutas definidas en `ApiController` tendrán el prefijo `/api`.
+
+### `version`
+
+El atributo `version` permite definir una versión para el controlador, que se incluirá en la ruta. Por ejemplo:
+
+```rust
+#[controller("/api", version = "v1")]
+struct ApiController;
+```
+
+Esto es equivalente a definir el controlador con el prefijo `/api/v1`. Sin embargo aporta semántica adicional, indicando que este controlador pertenece a la versión 1 de la API.

docs/es/key-concepts/controllers/definition.md

@@ -0,0 +1,64 @@
+# Definiendo rutas en controladores
+
+En Sword, las rutas se definen dentro del bloque de implementación de un controlador. Para ello debes utilizar la macro `#[routes]` sobre este bloque `impl`.
+
+```rust
+use sword::prelude::*;
+use serde_json::Value;
+
+#[controller("/api")]
+struct ApiController;
+
+#[routes]
+impl ApiController {
+    #[get("/hello")]
+    async fn hello(&self) -> HttpResponse {
+        HttpResponse::Ok().message("Hello, world!")
+    }
+}
+```
+
+Un controlador puede tener acceso al contexto de la `request` mediante el parámetro `ctx: Context`
+
+```rust
+use sword::prelude::*;
+
+#[controller("/api")]
+struct ApiController;
+
+#[routes]
+impl ApiController {
+    #[get("/hello/{name}")]
+    async fn hello(&self, ctx: Context) -> HttpResult<HttpResponse> {
+        let name: String = ctx.param("name")?;
+
+        Ok(HttpResponse::Ok().message(format!("Hello, {}!", name)))
+    }
+}
+```
+
+Para conocer todas las funcionalidades de `Context`, ver [Contexto de la Request](../context-requests.md).
+
+## Métodos HTTP soportados
+
+De momento, sword soporta los metódos HTTP más comunes:
+
+- `#[get("...")]`
+- `#[post("...")]`
+- `#[put("...")]`
+- `#[delete("...")]`
+- `#[patch("...")]`
+
+### Sintaxis de las rutas
+
+Las rutas pueden incluir parámetros, que se definen encerrando el nombre del parámetro entre llaves `{}`. Por ejemplo, en la ruta `/users/{id}`, `{id}` es un parámetro que puede ser extraído desde el contexto de la request.
+
+Para más detalles sobre la sintaxis de las rutas, puedes [consultar la documentación de axum](https://docs.rs/axum/latest/axum/routing/struct.Router.html#method.route)
+
+## Uso de `async`
+
+Sword está construido sobre `axum`, que utiliza `tokio` como runtime asíncrono. Por lo tanto, todos los métodos de los controladores deben ser `async`, incluso si no realizan operaciones asíncronas dentro del cuerpo del método.
+
+## Uso de `&self`
+
+Como te habrás percatado, los métodos de los controladores reciben `&self` como primer parámetro. Esto permite que los controladores puedan inyectar dependencias a través de sus campos. Sin embargo, este tema se abordará en detalle en la sección de [Inyección de Dependencias](../dependency-injection.md).