Use utoipa crate to generate and serve basic OpenAPI description

Author: Turbo87

Cargo.lock

@@ -125,6 +125,8 @@ tracing-subscriber = { version = "=0.3.19", features = ["env-filter", "json"] }
 typomania = { version = "=0.1.2", default-features = false }
 url = "=2.5.4"
 unicode-xid = "=0.2.6"
+utoipa = "=5.2.0"
+utoipa-axum = "=0.1.2"
 
 [dev-dependencies]
 bytes = "=1.9.0"

Cargo.toml

@@ -44,6 +44,7 @@ mod licenses;
 pub mod metrics;
 pub mod middleware;
 pub mod models;
+pub mod openapi;
 pub mod rate_limiter;
 mod real_ip;
 mod router;

src/lib.rs

@@ -0,0 +1,30 @@
+use utoipa::OpenApi;
+use utoipa_axum::router::OpenApiRouter;
+
+#[derive(OpenApi)]
+pub struct BaseOpenApi;
+
+impl BaseOpenApi {
+    pub fn router<S>() -> OpenApiRouter<S>
+    where
+        S: Send + Sync + Clone + 'static,
+    {
+        OpenApiRouter::with_openapi(Self::openapi())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use crate::tests::util::{RequestHelper, TestApp};
+    use http::StatusCode;
+    use insta::assert_json_snapshot;
+
+    #[tokio::test(flavor = "multi_thread")]
+    async fn test_openapi_snapshot() {
+        let (_app, anon) = TestApp::init().empty().await;
+
+        let response = anon.get::<()>("/api/openapi.json").await;
+        assert_eq!(response.status(), StatusCode::OK);
+        assert_json_snapshot!(response.json());
+    }
+}

src/openapi.rs

@@ -1,19 +1,22 @@
 use axum::extract::DefaultBodyLimit;
 use axum::response::IntoResponse;
 use axum::routing::{delete, get, post, put};
-use axum::Router;
+use axum::{Json, Router};
 use http::{Method, StatusCode};
 
 use crate::app::AppState;
 use crate::controllers::user::update_user;
 use crate::controllers::*;
+use crate::openapi::BaseOpenApi;
 use crate::util::errors::not_found;
 use crate::Env;
 
 const MAX_PUBLISH_CONTENT_LENGTH: usize = 128 * 1024 * 1024; // 128 MB
 
 pub fn build_axum_router(state: AppState) -> Router<()> {
-    let mut router = Router::new()
+    let (router, openapi) = BaseOpenApi::router().split_for_parts();
+
+    let mut router = router
         // Route used by both `cargo search` and the frontend
         .route("/api/v1/crates", get(krate::search::search))
         // Routes used by `cargo`
@@ -174,6 +177,7 @@ pub fn build_axum_router(state: AppState) -> Router<()> {
     }
 
     router
+        .route("/api/openapi.json", get(|| async { Json(openapi) }))
         .fallback(|method: Method| async move {
             match method {
                 Method::HEAD => StatusCode::NOT_FOUND.into_response(),

src/router.rs

@@ -0,0 +1,22 @@
+---
+source: src/openapi.rs
+expression: response.json()
+snapshot_kind: text
+---
+{
+  "components": {},
+  "info": {
+    "contact": {
+      "email": "[email protected]",
+      "name": "Alex Crichton"
+    },
+    "description": "Backend of crates.io",
+    "license": {
+      "name": "MIT OR Apache-2.0"
+    },
+    "title": "crates_io",
+    "version": "0.0.0"
+  },
+  "openapi": "3.1.0",
+  "paths": {}
+}