feat: OpenAPI integration

Cargo.toml

@@ -35,6 +35,11 @@ auth_jwt = ["dep:jsonwebtoken"]
 cli = ["dep:clap"]
 testing = ["dep:axum-test", "dep:scraper"]
 with-db = ["dep:sea-orm", "dep:sea-orm-migration", "loco-gen/with-db"]
+# OpenAPI features
+all_openapi = ["openapi_swagger", "openapi_redoc", "openapi_scalar"]
+openapi_swagger = ["dep:utoipa", "dep:utoipa-axum", "dep:utoipa-swagger-ui"]
+openapi_redoc = ["dep:utoipa", "dep:utoipa-axum", "dep:utoipa-redoc"]
+openapi_scalar = ["dep:utoipa", "dep:utoipa-axum", "dep:utoipa-scalar"]
 # Storage features
 all_storage = ["storage_aws_s3", "storage_azure", "storage_gcp"]
 storage_aws_s3 = ["opendal/services-s3"]
@@ -130,6 +135,13 @@ cfg-if = "1"
 
 uuid = { version = "1.10.0", features = ["v4", "fast-rng"] }
 
+# OpenAPI
+utoipa = { workspace = true, optional = true }
+utoipa-axum = { workspace = true, optional = true }
+utoipa-swagger-ui = { workspace = true, optional = true }
+utoipa-redoc = { workspace = true, optional = true }
+utoipa-scalar = { workspace = true, optional = true }
+
 # File Upload
 opendal = { version = "0.50.2", default-features = false, features = [
     "services-memory",
@@ -183,6 +195,13 @@ tower-http = { version = "0.6.1", features = [
 ] }
 heck = "0.4.0"
 
+# OpenAPI
+utoipa = { version = "5.0.0", features = ["yaml"] }
+utoipa-axum = { version = "0.2.0" }
+utoipa-swagger-ui = { version = "9.0", features = ["axum", "vendored"] }
+utoipa-redoc = { version = "6.0.0", features = ["axum"] }
+utoipa-scalar = { version = "0.3.0", features = ["axum"] }
+
 [dependencies.sea-orm-migration]
 optional = true
 version = "1.0.0"
@@ -201,7 +220,12 @@ features = ["testing"]
 [dev-dependencies]
 loco-rs = { path = ".", features = ["testing"] }
 rstest = "0.21.0"
-insta = { version = "1.34.0", features = ["redactions", "yaml", "filters"] }
+insta = { version = "1.34.0", features = [
+    "redactions",
+    "yaml",
+    "json",
+    "filters",
+] }
 tree-fs = { version = "0.2.1" }
 reqwest = { version = "0.12.7" }
 serial_test = "3.1.1"

docs-site/content/docs/the-app/controller.md

@@ -113,7 +113,7 @@ Note that by-design _sharing state between controllers and workers have no meani
 
 ### Shared state in tasks
 
-Tasks don't really have a value for shared state, as they have a similar life as any exec'd binary. The process fires up, boots, creates all resources needed (connects to db, etc.), performs the task logic, and then the 
+Tasks don't really have a value for shared state, as they have a similar life as any exec'd binary. The process fires up, boots, creates all resources needed (connects to db, etc.), performs the task logic, and then the
 
 ## Routes in Controllers
 
@@ -416,7 +416,7 @@ By default, Loco uses Bearer authentication for JWT. However, you can customize
   auth:
     # JWT authentication
     jwt:
-      location: 
+      location:
         from: Cookie
         name: token
   ...
@@ -427,7 +427,7 @@ By default, Loco uses Bearer authentication for JWT. However, you can customize
   auth:
     # JWT authentication
     jwt:
-      location: 
+      location:
         from: Query
         name: token
   ...
@@ -700,7 +700,7 @@ middlewares:
 ```
 
 ## CORS
-This middleware enables Cross-Origin Resource Sharing (CORS) by allowing configurable origins, methods, and headers in HTTP requests. 
+This middleware enables Cross-Origin Resource Sharing (CORS) by allowing configurable origins, methods, and headers in HTTP requests.
 It can be tailored to fit various application requirements, supporting permissive CORS or specific rules as defined in the middleware configuration.
 
 ```yaml
@@ -764,6 +764,134 @@ impl Hooks for App {
 }
 ```
 
+# OpenAPI Integration Setup
+The Loco OpenAPI integration is generated using [`Utoipa`](https://github.com/juhaku/utoipa)
+
+## `Cargo.toml` features flages
+Edit your `Cargo.toml` file and add one or multiple of the following features flages:
+- `openapi_swagger`
+- `openapi_redoc`
+- `openapi_scalar`
+- `all_openapi`
+
+```toml
+[workspace.dependencies]
+loco-rs = { version = "0.14", features = [
+    "openapi_scalar",
+] }
+```
+
+## Configuration
+Add the corresponding OpenAPI visualizer to the config file
+```yaml
+#...
+server:
+  ...
+  openapi:
+    redoc:
+      !Redoc
+        url: /redoc
+        # spec_json_url: /redoc/openapi.json
+        # spec_yaml_url: /redoc/openapi.yaml
+    scalar:
+      !Scalar
+        url: /scalar
+        # spec_json_url: /scalar/openapi.json
+        # spec_yaml_url: /scalar/openapi.yaml
+    swagger:
+      !Swagger
+        url: /swagger-ui
+        spec_json_url: /api-docs/openapi.json # spec_json_url is required for swagger-ui
+        # spec_yaml_url: /api-docs/openapi.yaml
+```
+## Inital OpenAPI Spec
+Modifies the OpenAPI spec before the routes are added, allowing you to edit [`openapi::info`](https://docs.rs/utoipa/latest/utoipa/openapi/info/struct.Info.html)
+
+```rust
+// src/app.rs
+use loco_rs::auth::openapi::{set_jwt_location_ctx, SecurityAddon};
+
+impl Hooks for App {
+    #...
+    fn inital_openapi_spec(ctx: &AppContext) -> utoipa::openapi::OpenApi {
+        #[derive(OpenApi)]
+        #[openapi(
+            modifiers(&SecurityAddon),
+            info(
+                title = "Loco Demo",
+                description = "This app is a kitchensink for various capabilities and examples of the [Loco](https://loco.rs) project."
+            )
+        )]
+        struct ApiDoc;
+        set_jwt_location_ctx(ctx);
+
+        ApiDoc::openapi()
+    }
+```
+
+## Generating the OpenAPI spec for a route
+Only routes that are annotated with [`utoipa::path`](https://docs.rs/utoipa/latest/utoipa/attr.path.html) will be included in the OpenAPI spec.
+
+```rust
+#[utoipa::path(
+    get,
+    path = "/album",
+    responses(
+        (status = 200, description = "Album found", body = Album),
+    ),
+)]
+async fn get_action_openapi() -> Result<Response> {
+    format::json(Album {
+        title: "VH II".to_string(),
+        rating: 10,
+    })
+}
+```
+
+Make sure to add `#[derive(ToSchema)]` on any struct that included in [`utoipa::path`](https://docs.rs/utoipa/latest/utoipa/attr.path.html).
+```rust
+#[derive(Serialize, Debug, ToSchema)]
+pub struct Album {
+    title: String,
+    rating: u32,
+}
+```
+
+If `modifiers(&SecurityAddon)` is set in `inital_openapi_spec`, you can document the per route security in `utoipa::path`:
+- `security(("jwt_token" = []))`
+- `security(("api_key" = []))`
+- or leave blank to remove security from the route `security(())`
+
+Example:
+```rust
+#[utoipa::path(
+    get,
+    path = "/album",
+    security(("jwt_token" = [])),
+    responses(
+        (status = 200, description = "Album found", body = Album),
+    ),
+)]
+```
+
+## Adding routes to the OpenAPI spec visualizer
+Swap the `axum::routing::MethodFilter` to `routes!`
+### Before
+```rust
+Routes::new()
+    .add("/album", get(get_action_openapi)),
+```
+### After
+```rust
+Routes::new()
+    .add("/album", routes!(get_action_openapi)),
+```
+### Note: do not add multiple routes inside the `routes!` macro
+```rust
+Routes::new()
+    .add("/album", routes!(get_action_1_do_not_do_this, get_action_2_do_not_do_this)),
+```
+
 # Request Validation
 `JsonValidate` extractor simplifies input [validation](https://github.com/Keats/validator) by integrating with the validator crate. Here's an example of how to validate incoming request data:
 
@@ -826,7 +954,7 @@ If you'd like to return validation errors in a structured JSON format, use `Json
     ]
   }
 }
-```  
+```
 
 # Pagination
 
@@ -925,7 +1053,7 @@ impl PaginationResponse {
 ```
 
 
-# Testing 
+# Testing
 When testing controllers, the goal is to call the router's controller endpoint and verify the HTTP response, including the status code, response content, headers, and more.
 
 To initialize a test request, use `use loco_rs::testing::prelude::*;`, which prepares your app routers, providing the request instance and the application context.

src/app.rs

@@ -222,6 +222,45 @@ pub trait Hooks: Send {
     /// This function allows users to perform any necessary cleanup or final
     /// actions before the application stops completely.
     async fn on_shutdown(_ctx: &AppContext) {}
+
+    /// Modifies the OpenAPI spec before the routes are added, allowing you to edit [openapi::info](https://docs.rs/utoipa/latest/utoipa/openapi/info/struct.Info.html)
+    /// # Examples
+    /// ```rust ignore
+    /// fn inital_openapi_spec(_ctx: &AppContext) -> utoipa::openapi::OpenApi {
+    ///     #[derive(OpenApi)]
+    ///     #[openapi(info(
+    ///         title = "Loco Demo",
+    ///         description = "This app is a kitchensink for various capabilities and examples of the [Loco](https://loco.rs) project."
+    ///     ))]
+    ///     struct ApiDoc;
+    ///     ApiDoc::openapi()
+    /// }
+    /// ```
+    ///
+    /// With SecurityAddon
+    /// ```rust ignore
+    /// fn inital_openapi_spec(ctx: &AppContext) -> utoipa::openapi::OpenApi {
+    ///     #[derive(OpenApi)]
+    ///     #[openapi(
+    ///         modifiers(&SecurityAddon),
+    ///         info(
+    ///             title = "Loco Demo",
+    ///             description = "This app is a kitchensink for various capabilities and examples of the [Loco](https://loco.rs) project."
+    ///         )
+    ///     )]
+    ///     struct ApiDoc;
+    ///     set_jwt_location_ctx(ctx);
+    ///
+    ///     ApiDoc::openapi()
+    /// }
+    /// ```
+    #[cfg(any(
+        feature = "openapi_swagger",
+        feature = "openapi_redoc",
+        feature = "openapi_scalar"
+    ))]
+    #[must_use]
+    fn inital_openapi_spec(_ctx: &AppContext) -> utoipa::openapi::OpenApi;
 }
 
 /// An initializer.

src/auth/mod.rs

@@ -1,2 +1,8 @@
 #[cfg(feature = "auth_jwt")]
 pub mod jwt;
+#[cfg(any(
+    feature = "openapi_swagger",
+    feature = "openapi_redoc",
+    feature = "openapi_scalar"
+))]
+pub mod openapi;

src/auth/openapi.rs

@@ -0,0 +1,68 @@
+use std::sync::OnceLock;
+
+use utoipa::{
+    openapi::security::{ApiKey, ApiKeyValue, HttpAuthScheme, HttpBuilder, SecurityScheme},
+    Modify,
+};
+
+use crate::{app::AppContext, config::JWTLocation};
+
+static JWT_LOCATION: OnceLock<Option<JWTLocation>> = OnceLock::new();
+
+#[must_use]
+pub fn get_jwt_location_from_ctx(ctx: &AppContext) -> JWTLocation {
+    ctx.config
+        .auth
+        .as_ref()
+        .and_then(|auth| auth.jwt.as_ref())
+        .and_then(|jwt| jwt.location.as_ref())
+        .unwrap_or(&JWTLocation::Bearer)
+        .clone()
+}
+
+pub fn set_jwt_location_ctx(ctx: &AppContext) {
+    set_jwt_location(get_jwt_location_from_ctx(ctx));
+}
+
+pub fn set_jwt_location(jwt_location: JWTLocation) -> &'static Option<JWTLocation> {
+    JWT_LOCATION.get_or_init(|| Some(jwt_location))
+}
+
+fn get_jwt_location() -> Option<&'static JWTLocation> {
+    JWT_LOCATION.get().unwrap_or(&None).as_ref()
+}
+
+pub struct SecurityAddon;
+
+/// Adds security to the `OpenAPI` doc, using the JWT location in the config
+impl Modify for SecurityAddon {
+    fn modify(&self, openapi: &mut utoipa::openapi::OpenApi) {
+        if let Some(jwt_location) = get_jwt_location() {
+            if let Some(components) = openapi.components.as_mut() {
+                components.add_security_schemes_from_iter([
+                    (
+                        "jwt_token",
+                        match jwt_location {
+                            JWTLocation::Bearer => SecurityScheme::Http(
+                                HttpBuilder::new()
+                                    .scheme(HttpAuthScheme::Bearer)
+                                    .bearer_format("JWT")
+                                    .build(),
+                            ),
+                            JWTLocation::Query { name } => {
+                                SecurityScheme::ApiKey(ApiKey::Query(ApiKeyValue::new(name)))
+                            }
+                            JWTLocation::Cookie { name } => {
+                                SecurityScheme::ApiKey(ApiKey::Cookie(ApiKeyValue::new(name)))
+                            }
+                        },
+                    ),
+                    (
+                        "api_key",
+                        SecurityScheme::ApiKey(ApiKey::Header(ApiKeyValue::new("apikey"))),
+                    ),
+                ]);
+            }
+        }
+    }
+}

src/cli.rs

@@ -176,7 +176,7 @@ enum ComponentArg {
     /// Generates a new model file for defining the data structure of your
     /// application, and test file logic.
     #[command(after_help = format!(
-    "{}  
+    "{}
   - Generate empty model:
       $ cargo loco g model posts
 
@@ -272,7 +272,7 @@ After running the migration, follow these steps to complete the process:
     },
     /// Generate a new controller with the given controller name, and test file.
     #[command(after_help = format!(
-    "{}  
+    "{}
   - Generate an empty controller:
       $ cargo loco generate controller posts --api