feat: better api docs (#6586)

* feat: docs

* fix tombi

* chore: fix some of the routes rendering with missing /

* response schemas

* fix: restore labrinth docs routes

* Fix path parameter docs in routes

* remove utoipa-actix-web

* consistency

* improve version intros

* improve formatting, examples

* better hash examples, move openapi stuff to openapi.rs

* more utoipa param fixes

* request body docs

* chore: remove moderation route from v2, remove ingest & webhooks from v3 spec

* fixes

* chore: tweak sources titles

* fix

* fix test

* improve examples

* increase compiler spawned thread stack size

* remove unused tests & script

* test

* bro what

* fix

---------

Co-authored-by: aecsocket <43144841+aecsocket@users.noreply.github.com>

apps/labrinth/src/routes/debug/mod.rs

@@ -1,29 +1,46 @@
 use std::time::Duration;
 
+use actix_web::web;
 use eyre::Context;
 use eyre::eyre;
 use prometheus::IntGauge;
 
+#[cfg(target_os = "linux")]
+use super::SecurityAddon;
 use crate::util::cors::default_cors;
 
 #[cfg(target_os = "linux")]
-mod pprof;
+pub(crate) mod pprof;
 
-pub fn config(cfg: &mut utoipa_actix_web::service_config::ServiceConfig) {
-    cfg.service(
-        utoipa_actix_web::scope("/debug")
-            .wrap(default_cors())
-            .configure({
-                #[cfg(target_os = "linux")]
-                {
-                    pprof::config
-                }
-                #[cfg(not(target_os = "linux"))]
-                {
-                    |_cfg| ()
-                }
-            }),
-    );
+#[cfg(target_os = "linux")]
+#[derive(utoipa::OpenApi)]
+#[openapi(
+	paths(pprof::heap, pprof::flame_graph),
+	modifiers(&DebugPathModifier, &SecurityAddon)
+)]
+pub struct ApiDoc;
+
+#[cfg(target_os = "linux")]
+struct DebugPathModifier;
+
+#[cfg(target_os = "linux")]
+impl utoipa::Modify for DebugPathModifier {
+    fn modify(&self, openapi: &mut utoipa::openapi::OpenApi) {
+        super::prefix_openapi_paths(openapi, "/debug", |_| false);
+    }
+}
+
+pub fn config(cfg: &mut actix_web::web::ServiceConfig) {
+    cfg.service(web::scope("/debug").wrap(default_cors()).configure({
+        #[cfg(target_os = "linux")]
+        {
+            pprof::config
+        }
+        #[cfg(not(target_os = "linux"))]
+        {
+            |_cfg| ()
+        }
+    }));
 }
 
 pub fn register_and_set_metrics(

apps/labrinth/src/routes/debug/pprof.rs

@@ -5,11 +5,19 @@ use eyre::{Context, eyre};
 use prometheus::{IntGauge, Registry};
 use std::time::Duration;
 
-pub fn config(cfg: &mut utoipa_actix_web::service_config::ServiceConfig) {
+pub fn config(cfg: &mut actix_web::web::ServiceConfig) {
     cfg.service(heap).service(flame_graph);
 }
 
-#[utoipa::path]
+/// Get a heap profile.  
+#[utoipa::path(
+	tag = "debug",
+	responses((
+		status = OK,
+		body = Vec<u8>,
+		content_type = "application/octet-stream"
+	))
+)]
 #[get("/pprof/heap", guard = "admin_key_guard")]
 pub async fn heap() -> Result<HttpResponse, ApiError> {
     let mut prof_ctl = jemalloc_pprof::PROF_CTL.as_ref().unwrap().lock().await;
@@ -23,7 +31,11 @@ pub async fn heap() -> Result<HttpResponse, ApiError> {
         .body(pprof))
 }
 
-#[utoipa::path]
+/// Get a heap flame graph.  
+#[utoipa::path(
+	tag = "debug",
+	responses((status = OK, body = String, content_type = "image/svg+xml"))
+)]
 #[get("/pprof/heap/flamegraph", guard = "admin_key_guard")]
 pub async fn flame_graph() -> Result<HttpResponse, ApiError> {
     let mut prof_ctl = jemalloc_pprof::PROF_CTL.as_ref().unwrap().lock().await;