Merge branches 'quenting/admin-api/doc' and 'quenting/admin-api/create-user' into quenting/admin-api/temp-merge-base

Author: sandhose

crates/handlers/src/admin/mod.rs

@@ -14,33 +14,59 @@
 
 use aide::{
     axum::ApiRouter,
-    openapi::{OAuth2Flow, OAuth2Flows, OpenApi, SecurityScheme, Server, ServerVariable},
+    openapi::{OAuth2Flow, OAuth2Flows, OpenApi, SecurityScheme, Server, Tag},
+};
+use axum::{
+    extract::{FromRef, FromRequestParts, State},
+    http::HeaderName,
+    response::Html,
+    Json, Router,
 };
-use axum::{extract::FromRequestParts, Json, Router};
 use hyper::header::{ACCEPT, AUTHORIZATION, CONTENT_TYPE};
 use indexmap::IndexMap;
+use mas_axum_utils::FancyError;
 use mas_http::CorsLayerExt;
-use mas_router::{OAuth2AuthorizationEndpoint, OAuth2TokenEndpoint, SimpleRoute};
+use mas_matrix::BoxHomeserverConnection;
+use mas_router::{
+    ApiDoc, ApiDocCallback, OAuth2AuthorizationEndpoint, OAuth2TokenEndpoint, Route, SimpleRoute,
+    UrlBuilder,
+};
+use mas_storage::BoxRng;
+use mas_templates::{ApiDocContext, Templates};
 use tower_http::cors::{Any, CorsLayer};
 
 mod call_context;
 mod model;
 mod params;
 mod response;
+mod schema;
 mod v1;
 
 use self::call_context::CallContext;
 
 pub fn router<S>() -> (OpenApi, Router<S>)
 where
     S: Clone + Send + Sync + 'static,
+    BoxHomeserverConnection: FromRef<S>,
+    BoxRng: FromRequestParts<S>,
     CallContext: FromRequestParts<S>,
+    Templates: FromRef<S>,
+    UrlBuilder: FromRef<S>,
 {
+    aide::gen::in_context(|ctx| {
+        ctx.schema = schemars::gen::SchemaGenerator::new(schemars::gen::SchemaSettings::openapi3());
+    });
+
     let mut api = OpenApi::default();
     let router = ApiRouter::<S>::new()
         .nest("/api/admin/v1", self::v1::router())
         .finish_api_with(&mut api, |t| {
             t.title("Matrix Authentication Service admin API")
+                .tag(Tag {
+                    name: "user".to_owned(),
+                    description: Some("Manage users".to_owned()),
+                    ..Tag::default()
+                })
                 .security_scheme(
                     "oauth2",
                     SecurityScheme::OAuth2 {
@@ -70,34 +96,62 @@ where
                     },
                 )
                 .security_requirement_scopes("oauth2", ["urn:mas:admin"])
-                .server(Server {
-                    url: "{base}".to_owned(),
-                    variables: IndexMap::from([(
-                        "base".to_owned(),
-                        ServerVariable {
-                            default: "/".to_owned(),
-                            ..ServerVariable::default()
-                        },
-                    )]),
-                    ..Server::default()
-                })
         });
 
     let router = router
         // Serve the OpenAPI spec as JSON
         .route(
             "/api/spec.json",
             axum::routing::get({
-                let res = Json(api.clone());
-                move || std::future::ready(res.clone())
+                let api = api.clone();
+                move |State(url_builder): State<UrlBuilder>| {
+                    // Let's set the servers to the HTTP base URL
+                    let mut api = api.clone();
+                    api.servers = vec![Server {
+                        url: url_builder.http_base().to_string(),
+                        ..Server::default()
+                    }];
+
+                    std::future::ready(Json(api))
+                }
             }),
         )
+        // Serve the Swagger API reference
+        .route(ApiDoc::route(), axum::routing::get(swagger))
+        .route(
+            ApiDocCallback::route(),
+            axum::routing::get(swagger_callback),
+        )
         .layer(
             CorsLayer::new()
                 .allow_origin(Any)
                 .allow_methods(Any)
-                .allow_otel_headers([AUTHORIZATION, ACCEPT, CONTENT_TYPE]),
+                .allow_otel_headers([
+                    AUTHORIZATION,
+                    ACCEPT,
+                    CONTENT_TYPE,
+                    // Swagger will send this header, so we have to allow it to avoid CORS errors
+                    HeaderName::from_static("x-requested-with"),
+                ]),
         );
 
     (api, router)
 }
+
+async fn swagger(
+    State(url_builder): State<UrlBuilder>,
+    State(templates): State<Templates>,
+) -> Result<Html<String>, FancyError> {
+    let ctx = ApiDocContext::from_url_builder(&url_builder);
+    let res = templates.render_swagger(&ctx)?;
+    Ok(Html(res))
+}
+
+async fn swagger_callback(
+    State(url_builder): State<UrlBuilder>,
+    State(templates): State<Templates>,
+) -> Result<Html<String>, FancyError> {
+    let ctx = ApiDocContext::from_url_builder(&url_builder);
+    let res = templates.render_swagger_callback(&ctx)?;
+    Ok(Html(res))
+}

crates/handlers/src/admin/params.rs

@@ -52,12 +52,8 @@ impl IntoResponse for UlidPathParamRejection {
 
 #[derive(JsonSchema, Debug, Clone, Copy, Deserialize)]
 struct UlidInPath {
-    #[schemars(
-        with = "String",
-        title = "ULID",
-        description = "A ULID as per https://github.com/ulid/spec",
-        regex(pattern = r"^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$")
-    )]
+    /// # The ID of the resource
+    #[schemars(with = "super::schema::Ulid")]
     id: Ulid,
 }
 
@@ -81,12 +77,12 @@ const DEFAULT_PAGE_SIZE: usize = 10;
 struct PaginationParams {
     /// Retrieve the items before the given ID
     #[serde(rename = "page[before]")]
-    #[schemars(with = "Option<String>")]
+    #[schemars(with = "Option<super::schema::Ulid>")]
     before: Option<Ulid>,
 
     /// Retrieve the items after the given ID
     #[serde(rename = "page[after]")]
-    #[schemars(with = "Option<String>")]
+    #[schemars(with = "Option<super::schema::Ulid>")]
     after: Option<Ulid>,
 
     /// Retrieve the first N items

crates/handlers/src/admin/response.rs

@@ -143,7 +143,7 @@ struct SingleResource<T> {
     type_: &'static str,
 
     /// The ID of the resource
-    #[schemars(with = "String")]
+    #[schemars(with = "super::schema::Ulid")]
     id: Ulid,
 
     /// The attributes of the resource

crates/handlers/src/admin/schema.rs

@@ -0,0 +1,56 @@
+// Copyright 2024 The Matrix.org Foundation C.I.C.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+//! Common schema definitions
+
+use schemars::{
+    gen::SchemaGenerator,
+    schema::{InstanceType, Metadata, Schema, SchemaObject, StringValidation},
+    JsonSchema,
+};
+
+/// A type to use for schema definitions of ULIDs
+///
+/// Use with `#[schemars(with = "crate::admin::schema::Ulid")]`
+pub struct Ulid;
+
+impl JsonSchema for Ulid {
+    fn schema_name() -> String {
+        "ULID".to_owned()
+    }
+
+    fn json_schema(_gen: &mut SchemaGenerator) -> Schema {
+        SchemaObject {
+            instance_type: Some(InstanceType::String.into()),
+
+            metadata: Some(Box::new(Metadata {
+                title: Some("ULID".into()),
+                description: Some("A ULID as per https://github.com/ulid/spec".into()),
+                examples: vec![
+                    "01ARZ3NDEKTSV4RRFFQ69G5FAV".into(),
+                    "01J41912SC8VGAQDD50F6APK91".into(),
+                ],
+                ..Metadata::default()
+            })),
+
+            string: Some(Box::new(StringValidation {
+                pattern: Some(r"^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$".into()),
+                ..StringValidation::default()
+            })),
+
+            ..SchemaObject::default()
+        }
+        .into()
+    }
+}

crates/handlers/src/admin/v1/mod.rs

@@ -13,7 +13,9 @@
 // limitations under the License.
 
 use aide::axum::{routing::get_with, ApiRouter};
-use axum::extract::FromRequestParts;
+use axum::extract::{FromRef, FromRequestParts};
+use mas_matrix::BoxHomeserverConnection;
+use mas_storage::BoxRng;
 
 use super::call_context::CallContext;
 
@@ -22,10 +24,16 @@ mod users;
 pub fn router<S>() -> ApiRouter<S>
 where
     S: Clone + Send + Sync + 'static,
+    BoxHomeserverConnection: FromRef<S>,
+    BoxRng: FromRequestParts<S>,
     CallContext: FromRequestParts<S>,
 {
     ApiRouter::<S>::new()
-        .api_route("/users", get_with(self::users::list, self::users::list_doc))
+        .api_route(
+            "/users",
+            get_with(self::users::list, self::users::list_doc)
+                .post_with(self::users::add, self::users::add_doc),
+        )
         .api_route(
             "/users/:id",
             get_with(self::users::get, self::users::get_doc),