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/v3/version_creation.rs

@@ -33,7 +33,7 @@ use crate::util::validate::validation_errors_to_string;
 use crate::validate::{ValidationResult, validate_file};
 use actix_multipart::{Field, Multipart};
 use actix_web::web::Data;
-use actix_web::{HttpRequest, HttpResponse, web};
+use actix_web::{HttpRequest, HttpResponse, post, web};
 use chrono::Utc;
 use futures::stream::StreamExt;
 use hex::ToHex;
@@ -104,6 +104,48 @@ struct InitialFileData {
 }
 
 // under `/api/v1/version`
+/// Create a version on an existing project.
+#[utoipa::path(
+	tag = "versions",
+	post,
+	request_body(
+		content(("multipart/form-data")),
+		description = "Multipart payload containing `data` and uploaded files"
+	),
+	responses(
+		(status = 200, description = "Expected response to a valid request", body = Version),
+		(status = 400, description = "Request was invalid, see given error"),
+		(
+			status = 401,
+			description = "Incorrect token scopes or no authorization to access the requested item(s)"
+		)
+	),
+	security(("bearer_auth" = ["VERSION_CREATE"]))
+)]
+#[post("/version")]
+pub async fn version_create_route(
+    req: HttpRequest,
+    payload: Multipart,
+    client: Data<PgPool>,
+    redis: Data<RedisPool>,
+    file_host: Data<dyn FileHost>,
+    session_queue: Data<AuthQueue>,
+    http: web::Data<HttpClient>,
+    search_state: Data<SearchState>,
+) -> Result<HttpResponse, CreateError> {
+    version_create(
+        req,
+        payload,
+        client,
+        redis,
+        file_host,
+        session_queue,
+        http,
+        search_state,
+    )
+    .await
+}
+
 pub async fn version_create(
     req: HttpRequest,
     mut payload: Multipart,
@@ -529,6 +571,56 @@ async fn version_create_inner(
     Ok((HttpResponse::Ok().json(response), project_id))
 }
 
+/// Add files to an existing version.
+#[utoipa::path(
+	tag = "versions",
+	post,
+	params(
+		("version_id" = VersionId, Path, description = "The ID of the version")
+	),
+	request_body(
+		content(("multipart/form-data")),
+		description = "Multipart payload containing files to upload"
+	),
+	responses(
+		(status = NO_CONTENT, description = "Expected response to a valid request"),
+		(
+			status = 401,
+			description = "Incorrect token scopes or no authorization to access the requested item(s)"
+		),
+		(
+			status = 404,
+			description = "The requested item(s) were not found or no authorization to access the requested item(s)"
+		)
+	),
+	security(("bearer_auth" = ["VERSION_WRITE"]))
+)]
+#[post("/version/{version_id}/file")]
+pub async fn upload_file_to_version_route(
+    req: HttpRequest,
+    url_data: web::Path<(VersionId,)>,
+    payload: Multipart,
+    client: Data<PgPool>,
+    redis: Data<RedisPool>,
+    file_host: Data<dyn FileHost>,
+    session_queue: web::Data<AuthQueue>,
+    http: web::Data<HttpClient>,
+    search_state: Data<SearchState>,
+) -> Result<HttpResponse, CreateError> {
+    upload_file_to_version(
+        req,
+        url_data,
+        payload,
+        client,
+        redis,
+        file_host,
+        session_queue,
+        http,
+        search_state,
+    )
+    .await
+}
+
 pub async fn upload_file_to_version(
     req: HttpRequest,
     url_data: web::Path<(VersionId,)>,