API doc changes

src/api/mod.rs

@@ -1,6 +1,12 @@
 use axum::{Json, Router};
 use serde::Serialize;
-use utoipa::{openapi::OpenApi, OpenApi as OpenApiTrait, ToSchema};
+use utoipa::{
+    openapi::{
+        security::{HttpAuthScheme, HttpBuilder, SecurityScheme},
+        OpenApi,
+    },
+    Modify, OpenApi as OpenApiTrait, ToSchema,
+};
 use utoipa_axum::{router::OpenApiRouter, routes};
 
 use crate::{
@@ -14,12 +20,32 @@ mod rivals;
 mod songs;
 
 #[derive(OpenApiTrait)]
-#[openapi(servers((url = "/api")), security(
+#[openapi(
+    modifiers(&SecurityAddon),
+    servers((url = "/api")), security(
     (),
     ("token_jwt" = [])
 ))]
 pub struct ApiDoc;
 
+struct SecurityAddon;
+
+impl Modify for SecurityAddon {
+    fn modify(&self, openapi: &mut utoipa::openapi::OpenApi) {
+        if let Some(components) = openapi.components.as_mut() {
+            components.add_security_scheme(
+                "token_jwt",
+                SecurityScheme::Http(
+                    HttpBuilder::new()
+                        .scheme(HttpAuthScheme::Bearer)
+                        .bearer_format("JWT")
+                        .build(),
+                ),
+            )
+        }
+    }
+}
+
 pub fn routes() -> (Router<AppState>, OpenApi) {
     OpenApiRouter::with_openapi(ApiDoc::openapi())
         .routes(routes!(health_check))
@@ -37,12 +63,17 @@ struct HealthCheck {
     radio_status: String,
 }
 
-/// Get health of the API.
+/// Get health of the server
 #[utoipa::path(
     method(get),
     path = "/healthCheck",
     responses(
-        (status = OK, description = "Success", body = HealthCheck, content_type = "application/json")
+        (status = OK, description = "Success",
+        body = HealthCheck, content_type = "application/json",
+        examples = (json!(r#"{ "status": "ok", "radioStatus": "2 song(s)" }"#))),
+        (status = OK, description = "Server works, but Radio is broken",
+        body = HealthCheck, content_type = "application/json",
+        example = json!(r#"{ "status": "ok", "radioStatus": "error" }"#)),
     )
 )]
 async fn health_check() -> Result<Json<HealthCheck>, RouteError> {

src/main.rs

@@ -1,4 +1,4 @@
-#![warn(    
+#![warn(
     clippy::nursery,
     clippy::correctness,
     clippy::style,
@@ -194,7 +194,7 @@ fn make_router(state: AppState) -> Router {
         .nest("//as_steamlogin", routes_steam_doubleslash()) // for that one edge case
         .nest("/as", routes_as(&state.config.radio.cgr_location))
         .nest("/api", api_router)
-        .merge(Scalar::with_url("/api-docs", openapi))
+        .merge(Scalar::with_url("/api/docs", openapi))
         .layer(session_layer)
         .layer(
             // TAKEN FROM: https://github.com/tokio-rs/axum/blob/d1fb14ead1063efe31ae3202e947ffd569875c0b/examples/error-handling/src/main.rs#L60-L77