Add more API docs

Cargo.toml

@@ -47,6 +47,6 @@ fred = { version = "9.3.0", features = ["i-sorted-sets"] }
 tower-sessions = "0.13.0"
 rmp-serde = "1.3.0"
 thiserror = "1.0"
-utoipa = { version = "5.1.3", features = ["axum_extras", "time"] }
+utoipa = { version = "5.1.3", features = ["axum_extras", "non_strict_integers", "repr", "time"] }
 utoipa-axum = "0.1.2"
 utoipa-scalar = { version = "0.2.0", features = ["axum"] }

src/api/mod.rs

@@ -22,7 +22,7 @@ mod songs;
 #[derive(OpenApiTrait)]
 #[openapi(
     modifiers(&SecurityAddon),
-    servers((url = "/api")), security(
+    servers((url = "/api"), (url = "/rust/api")), security(
     (),
     ("token_jwt" = [])
 ))]
@@ -70,13 +70,22 @@ struct HealthCheck {
     responses(
         (status = OK, description = "Success",
         body = HealthCheck, content_type = "application/json",
-        example = json!(r#"{ "status": "ok", "radioStatus": "2 song(s)" }"#)),
+        example = json!(HealthCheck {
+            status: "ok",
+            radio_status: "1 song(s)".to_owned()
+        })),
         (status = OK, description = "Server works, Radio has no songs",
         body = HealthCheck, content_type = "application/json",
-        example = json!(r#"{ "status": "ok", "radioStatus": "no songs" }"#)),
+        example = json!(HealthCheck {
+            status: "ok",
+            radio_status: "no songs".to_owned()
+        })),
         (status = OK, description = "Server works, but Radio is broken",
         body = HealthCheck, content_type = "application/json",
-        example = json!(r#"{ "status": "ok", "radioStatus": "error" }"#)),
+        example = json!(HealthCheck {
+            status: "ok",
+            radio_status: "error".to_owned()
+        })),
     )
 )]
 async fn health_check() -> Result<Json<HealthCheck>, RouteError> {

src/api/players.rs

@@ -6,7 +6,9 @@ use axum::{
 use diesel::prelude::*;
 use diesel_async::RunQueryDsl;
 use serde::Serialize;
+use utoipa::ToSchema;
 use utoipa_axum::router::OpenApiRouter;
+use utoipa_axum::routes;
 
 use crate::{
     models::players::{Player, PlayerPublic},
@@ -16,17 +18,34 @@ use crate::{
 
 pub fn routes() -> OpenApiRouter<AppState> {
     OpenApiRouter::new()
-        .route("/:id", get(get_player))
+        .routes(routes!(get_player))
         .route("/self", get(get_self))
 }
 
-#[derive(Serialize)]
+#[derive(Serialize, ToSchema)]
 #[serde(rename_all = "camelCase")]
 struct PlayerResponse {
     #[serde(flatten)]
     player: PlayerPublic,
 }
 
+//todo: move example for PlayerPublic to that struct itself
+
+/// Get a player by ID
+#[utoipa::path(
+    method(get),
+    path = "/{id}",
+    responses(
+        (status = OK, description = "Success",
+        body = PlayerResponse, content_type = "application/json",
+        example = json!(r#"{
+        "id":1,
+        "username":"m1nt_",
+        "accountType":2,
+        "joinedAt":"+002023-05-23T18:56:24.726000000Z",
+        "avatarUrl":"https://avatars.steamstatic.com/d72c8ef0f183faf564b9407572d51751794acd15_full.jpg"}"#))
+    )
+)]
 async fn get_player(
     State(state): State<AppState>,
     Path(id): Path<i32>,

src/main.rs

@@ -24,8 +24,7 @@ use std::{io::stdout, sync::Arc};
 use anyhow::{anyhow, Context};
 use axum::{
     extract::{MatchedPath, Request},
-    routing::get,
-    Json, Router,
+    Router,
 };
 use clap::Parser;
 use diesel::pg::Pg;
@@ -50,13 +49,10 @@ use tracing_appender::rolling::{RollingFileAppender, Rotation};
 use tracing_subscriber::{
     fmt::writer::MakeWriterExt, layer::SubscriberExt, util::SubscriberInitExt,
 };
-use util::{errors::RouteError, session_store::RedisStore};
+use util::session_store::RedisStore;
 use utoipa_scalar::{Scalar, Servable};
 
-use crate::{
-    api::routes,
-    game::{routes_as, routes_steam, routes_steam_doubleslash},
-};
+use crate::game::{routes_as, routes_steam, routes_steam_doubleslash};
 pub const MIGRATIONS: EmbeddedMigrations = embed_migrations!();
 
 /// Wavebreaker-specific user agent

src/models/players.rs

@@ -13,6 +13,7 @@ use num_enum::{IntoPrimitive, TryFromPrimitive};
 use serde::{Deserialize, Serialize};
 use serde_repr::{Deserialize_repr, Serialize_repr};
 use steam_rs::steam_id::SteamId;
+use utoipa::ToSchema;
 
 use super::rivalries::RivalryView;
 use crate::{
@@ -60,6 +61,7 @@ where
     Copy,
     TryFromPrimitive,
     IntoPrimitive,
+    ToSchema,
 )]
 #[diesel(sql_type = diesel::sql_types::SmallInt)]
 #[repr(i16)]
@@ -258,7 +260,7 @@ impl<'a> NewPlayer<'a> {
     }
 }
 
-#[derive(Selectable, Queryable, Debug, Serialize, Deserialize)]
+#[derive(Selectable, Queryable, Debug, Serialize, Deserialize, ToSchema)]
 #[serde(rename_all = "camelCase")]
 #[diesel(table_name = players, check_for_backend(diesel::pg::Pg))]
 pub struct PlayerPublic {