fix(repo): Adjust SwaggerUI to work with custom servers

Author: pedronauck

crates/web-utils/src/router_builder.rs

@@ -8,18 +8,18 @@ use axum::{
 };
 use tower::{Layer, Service};
 
-use super::server::server_builder::with_prefixed_route;
-
 pub struct RouterBuilder<S: Send + Sync + Clone + 'static> {
     router: Router<S>,
     base_path: String,
+    prefix: Option<String>,
 }
 
 impl<S: Send + Sync + Clone + 'static> RouterBuilder<S> {
     pub fn new(base_path: &str) -> Self {
         Self {
             router: Router::new(),
-            base_path: with_prefixed_route(base_path),
+            base_path: Self::safe_path(base_path),
+            prefix: None,
         }
     }
 
@@ -61,8 +61,32 @@ impl<S: Send + Sync + Clone + 'static> RouterBuilder<S> {
         self
     }
 
+    pub fn with_prefix(mut self, prefix: &str) -> Self {
+        self.prefix = Some(prefix.to_string());
+        self
+    }
+
     pub fn build(self) -> (String, Router<S>) {
-        let path = self.path();
+        let path = match self.prefix {
+            Some(prefix) => Self::prefixed_route(&prefix, &self.base_path),
+            None => self.base_path,
+        };
         (path, self.router)
     }
+
+    fn safe_path(path: &str) -> String {
+        if path.starts_with("/") {
+            path.to_string()
+        } else {
+            format!("/{}", path)
+        }
+    }
+
+    fn prefixed_route(prefix: &str, route: &str) -> String {
+        if route.starts_with('/') {
+            format!("{prefix}/{}", route.trim_start_matches('/'))
+        } else {
+            format!("{prefix}/{route}")
+        }
+    }
 }

crates/web-utils/src/server/server_builder.rs

@@ -22,14 +22,7 @@ use super::{
 };
 
 pub const API_VERSION: &str = "v1";
-
-pub fn with_prefixed_route(route: &str) -> String {
-    if route.starts_with('/') {
-        format!("/api/{}/{}", API_VERSION, route.trim_start_matches('/'))
-    } else {
-        format!("/api/{}/{}", API_VERSION, route)
-    }
-}
+pub const API_BASE_PATH: &str = "/api/v1";
 
 pub struct Server {
     app: Router,
@@ -65,8 +58,8 @@ impl ServerBuilder {
         port: u16,
     ) -> Server {
         let app = Router::new()
-            .route(&with_prefixed_route("health"), get(get_health::<S>))
-            .route(&with_prefixed_route("metrics"), get(get_metrics::<S>))
+            .route("/health", get(get_health::<S>))
+            .route("/metrics", get(get_metrics::<S>))
             .layer(TraceLayer::new_for_http().make_span_with(
                 |request: &Request<_>| {
                     let matched_path = request

postman/fuel-rest.postman.json

@@ -20,28 +20,32 @@
         }
       ],
       "request": {
+        "auth": {
+          "type": "bearer",
+          "bearer": [
+            {
+              "key": "token",
+              "value": "{{api_key}}",
+              "type": "string"
+            }
+          ]
+        },
         "method": "POST",
         "header": [],
         "body": {
           "mode": "raw",
-          "raw": "{\n    \"username\": \"petko\"\n}",
+          "raw": "{\n    \"username\": \"petko\", \"role\": \"BUILDER\"\n}",
           "options": {
             "raw": {
               "language": "json"
             }
           }
         },
         "url": {
-          "raw": "http://{{base_url}}/key/generate?password={{fuel_password}}",
+          "raw": "http://{{base_url}}/keys/generate",
           "protocol": "http",
           "host": ["{{base_url}}"],
-          "path": ["key", "generate"],
-          "query": [
-            {
-              "key": "password",
-              "value": "{{fuel_password}}"
-            }
-          ]
+          "path": ["key", "generate"]
         },
         "description": "This is a GET request and it is used to \"get\" data from an endpoint. There is no request body for a GET request, but you can use query parameters to help specify the resource you want data on (e.g., in this request, we have `id=1`).\n\nA successful GET response will have a `200 OK` status, and should include some kind of response body - for example, HTML web content or JSON data."
       },

services/api/src/server/handlers/open_api.rs

@@ -48,8 +48,12 @@ use fuel_streams_domains::{
     receipts::queryable::ReceiptsQuery,
     transactions::queryable::TransactionsQuery,
 };
+use fuel_web_utils::server::server_builder::API_BASE_PATH;
 use utoipa::{
-    openapi::security::{ApiKey, ApiKeyValue, SecurityScheme},
+    openapi::{
+        security::{HttpAuthScheme, HttpBuilder, SecurityScheme},
+        Server,
+    },
     Modify,
     OpenApi,
 };
@@ -67,11 +71,20 @@ struct SecurityAddon;
 
 impl Modify for SecurityAddon {
     fn modify(&self, openapi: &mut utoipa::openapi::OpenApi) {
-        let components = openapi.components.as_mut().unwrap(); // we can unwrap safely since there already is components registered.
-        components.add_security_scheme(
+        openapi.components.as_mut().unwrap().add_security_scheme(
             "api_key",
-            SecurityScheme::ApiKey(ApiKey::Header(ApiKeyValue::new("api_key"))),
-        )
+            SecurityScheme::Http(
+                HttpBuilder::new().scheme(HttpAuthScheme::Bearer).build(),
+            ),
+        );
+    }
+}
+
+struct ServerAddon;
+
+impl Modify for ServerAddon {
+    fn modify(&self, openapi: &mut utoipa::openapi::OpenApi) {
+        openapi.servers = Some(vec![Server::new(API_BASE_PATH)])
     }
 }
 
@@ -166,6 +179,6 @@ use super::{
         (name = "Receipts", description = "Receipts retrieval endpoints"),
         (name = "Transactions", description = "Transactions retrieval endpoints"),
     ),
-    modifiers(&SecurityAddon)
+    modifiers(&SecurityAddon, &ServerAddon)
 )]
 pub struct ApiDoc;

services/api/src/server/routes.rs

@@ -13,6 +13,7 @@ use fuel_streams_store::{db::DbItem, record::RecordPointer};
 use fuel_web_utils::{
     api_key::middleware::ApiKeyMiddleware,
     router_builder::RouterBuilder,
+    server::server_builder::API_BASE_PATH,
 };
 use open_api::ApiDoc;
 use serde::Serialize;
@@ -204,7 +205,7 @@ pub fn create_routes(state: &ServerState) -> Router {
         ))
         .build();
 
-    let (key_path, key_router) = RouterBuilder::new("/key")
+    let (key_path, key_router) = RouterBuilder::new("/keys")
         .related("/generate", post(api_key::generate_api_key))
         .with_layer(from_fn(api_key::validate_manage_api_keys_scope))
         .with_layer(from_fn_with_state(
@@ -213,14 +214,16 @@ pub fn create_routes(state: &ServerState) -> Router {
         ))
         .build();
 
-    app.nest(&blocks_path, blocks_router)
+    let routes = Router::new()
+        .nest(&blocks_path, blocks_router)
         .nest(&accounts_path, accounts_router)
         .nest(&contracts_path, contracts_router)
         .nest(&inputs_path, inputs_router)
         .nest(&outputs_path, outputs_router)
         .nest(&receipts_path, receipts_router)
         .nest(&transactions_path, transactions_router)
         .nest(&utxos_path, utxos_router)
-        .nest(&key_path, key_router)
-        .with_state(state.clone())
+        .nest(&key_path, key_router);
+
+    app.nest(API_BASE_PATH, routes).with_state(state.clone())
 }

services/webserver/src/server/routes.rs

@@ -2,6 +2,7 @@ use axum::{middleware::from_fn_with_state, routing::get, Router};
 use fuel_web_utils::{
     api_key::middleware::ApiKeyMiddleware,
     router_builder::RouterBuilder,
+    server::server_builder::API_BASE_PATH,
 };
 
 use super::handlers;
@@ -15,11 +16,15 @@ pub fn create_routes(state: &ServerState) -> Router {
 
     let (ws_path, ws_router) = RouterBuilder::new("/ws")
         .root(get(handlers::websocket::get_websocket))
-        .with_layer(from_fn_with_state(
-            auth_params.clone(),
-            ApiKeyMiddleware::handler,
-        ))
         .build();
 
-    app.nest(&ws_path, ws_router).with_state(state.to_owned())
+    let routes =
+        Router::new()
+            .nest(&ws_path, ws_router)
+            .layer(from_fn_with_state(
+                auth_params.clone(),
+                ApiKeyMiddleware::handler,
+            ));
+
+    app.nest(API_BASE_PATH, routes).with_state(state.clone())
 }