Merge branch 'quenting/admin-api/doc' into quenting/admin-api/temp-merge-base

Author: sandhose

crates/handlers/src/admin/mod.rs

@@ -14,13 +14,23 @@
 
 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_router::{
+    ApiDoc, ApiDocCallback, OAuth2AuthorizationEndpoint, OAuth2TokenEndpoint, Route, SimpleRoute,
+    UrlBuilder,
+};
+use mas_templates::{ApiDocContext, Templates};
 use tower_http::cors::{Any, CorsLayer};
 
 mod call_context;
@@ -35,12 +45,19 @@ pub fn router<S>() -> (OpenApi, Router<S>)
 where
     S: Clone + Send + Sync + 'static,
     CallContext: FromRequestParts<S>,
+    Templates: FromRef<S>,
+    UrlBuilder: FromRef<S>,
 {
     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 +87,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/v1/users/by_username.rs

@@ -58,7 +58,8 @@ pub struct UsernamePathParam {
 
 pub fn doc(operation: TransformOperation) -> TransformOperation {
     operation
-        .description("Get a user by its username (localpart)")
+        .summary("Get a user by its username (localpart)")
+        .tag("user")
         .response_with::<200, Json<SingleResponse<User>>, _>(|t| {
             let [sample, ..] = User::samples();
             let response =

crates/handlers/src/admin/v1/users/get.rs

@@ -52,7 +52,8 @@ impl IntoResponse for RouteError {
 
 pub fn doc(operation: TransformOperation) -> TransformOperation {
     operation
-        .description("Get a user")
+        .summary("Get a user")
+        .tag("user")
         .response_with::<200, Json<SingleResponse<User>>, _>(|t| {
             let [sample, ..] = User::samples();
             let response = SingleResponse::new_canonical(sample);

crates/handlers/src/admin/v1/users/list.rs

@@ -100,7 +100,8 @@ impl IntoResponse for RouteError {
 
 pub fn doc(operation: TransformOperation) -> TransformOperation {
     operation
-        .description("List users")
+        .summary("List users")
+        .tag("user")
         .response_with::<200, Json<PaginatedResponse<User>>, _>(|t| {
             let users = User::samples();
             let pagination = mas_storage::Pagination::first(users.len());

crates/handlers/src/bin/api-schema.rs

@@ -23,6 +23,9 @@
 
 use std::io::Write;
 
+use aide::openapi::{Server, ServerVariable};
+use indexmap::IndexMap;
+
 /// This is a dummy state, it should never be used.
 ///
 /// We use it to generate the API schema, which doesn't execute any request.
@@ -58,10 +61,25 @@ macro_rules! impl_from_ref {
 impl_from_request_parts!(mas_storage::BoxRepository);
 impl_from_request_parts!(mas_storage::BoxClock);
 impl_from_request_parts!(mas_handlers::BoundActivityTracker);
-impl_from_ref!(mas_keystore::Keystore);
+impl_from_ref!(mas_router::UrlBuilder);
+impl_from_ref!(mas_templates::Templates);
 
 fn main() -> Result<(), Box<dyn std::error::Error>> {
-    let (api, _) = mas_handlers::admin_api_router::<DummyState>();
+    let (mut api, _) = mas_handlers::admin_api_router::<DummyState>();
+
+    // Set the server list to a configurable base URL
+    api.servers = vec![Server {
+        url: "{base}".to_owned(),
+        variables: IndexMap::from([(
+            "base".to_owned(),
+            ServerVariable {
+                default: "/".to_owned(),
+                ..ServerVariable::default()
+            },
+        )]),
+        ..Server::default()
+    }];
+
     let mut stdout = std::io::stdout();
     serde_json::to_writer_pretty(&mut stdout, &api)?;
 

crates/router/src/endpoints.rs

@@ -870,3 +870,24 @@ pub struct GraphQLPlayground;
 impl SimpleRoute for GraphQLPlayground {
     const PATH: &'static str = "/graphql/playground";
 }
+
+/// `GET /api/spec.json`
+pub struct ApiSpec;
+
+impl SimpleRoute for ApiSpec {
+    const PATH: &'static str = "/api/spec.json";
+}
+
+/// `GET /api/doc/`
+pub struct ApiDoc;
+
+impl SimpleRoute for ApiDoc {
+    const PATH: &'static str = "/api/doc/";
+}
+
+/// `GET /api/doc/oauth2-callback`
+pub struct ApiDocCallback;
+
+impl SimpleRoute for ApiDocCallback {
+    const PATH: &'static str = "/api/doc/oauth2-callback";
+}

crates/router/src/url_builder.rs

@@ -28,7 +28,9 @@ pub struct UrlBuilder {
 }
 
 impl UrlBuilder {
-    fn absolute_url_for<U>(&self, destination: &U) -> Url
+    /// Create an absolute URL for a route
+    #[must_use]
+    pub fn absolute_url_for<U>(&self, destination: &U) -> Url
     where
         U: Route,
     {

crates/templates/src/context.rs

@@ -337,6 +337,35 @@ impl TemplateContext for AppContext {
     }
 }
 
+/// Context used by the `swagger/doc.html` template
+#[derive(Serialize)]
+pub struct ApiDocContext {
+    openapi_url: Url,
+    callback_url: Url,
+}
+
+impl ApiDocContext {
+    /// Constructs a context for the API documentation page giben the
+    /// [`UrlBuilder`]
+    #[must_use]
+    pub fn from_url_builder(url_builder: &UrlBuilder) -> Self {
+        Self {
+            openapi_url: url_builder.absolute_url_for(&mas_router::ApiSpec),
+            callback_url: url_builder.absolute_url_for(&mas_router::ApiDocCallback),
+        }
+    }
+}
+
+impl TemplateContext for ApiDocContext {
+    fn sample(_now: chrono::DateTime<Utc>, _rng: &mut impl Rng) -> Vec<Self>
+    where
+        Self: Sized,
+    {
+        let url_builder = UrlBuilder::new("https://example.com/".parse().unwrap(), None, None);
+        vec![Self::from_url_builder(&url_builder)]
+    }
+}
+
 /// Fields of the login form
 #[derive(Serialize, Deserialize, Debug, Clone, Copy, Hash, PartialEq, Eq)]
 #[serde(rename_all = "snake_case")]

crates/templates/src/lib.rs

@@ -42,16 +42,16 @@ mod macros;
 
 pub use self::{
     context::{
-        AppContext, CompatSsoContext, ConsentContext, DeviceConsentContext, DeviceLinkContext,
-        DeviceLinkFormField, EmailAddContext, EmailRecoveryContext, EmailVerificationContext,
-        EmailVerificationPageContext, EmptyContext, ErrorContext, FormPostContext, IndexContext,
-        LoginContext, LoginFormField, NotFoundContext, PolicyViolationContext, PostAuthContext,
-        PostAuthContextInner, ReauthContext, ReauthFormField, RecoveryExpiredContext,
-        RecoveryFinishContext, RecoveryFinishFormField, RecoveryProgressContext,
-        RecoveryStartContext, RecoveryStartFormField, RegisterContext, RegisterFormField,
-        SiteBranding, SiteConfigExt, SiteFeatures, TemplateContext, UpstreamExistingLinkContext,
-        UpstreamRegister, UpstreamRegisterFormField, UpstreamSuggestLink, WithCaptcha, WithCsrf,
-        WithLanguage, WithOptionalSession, WithSession,
+        ApiDocContext, AppContext, CompatSsoContext, ConsentContext, DeviceConsentContext,
+        DeviceLinkContext, DeviceLinkFormField, EmailAddContext, EmailRecoveryContext,
+        EmailVerificationContext, EmailVerificationPageContext, EmptyContext, ErrorContext,
+        FormPostContext, IndexContext, LoginContext, LoginFormField, NotFoundContext,
+        PolicyViolationContext, PostAuthContext, PostAuthContextInner, ReauthContext,
+        ReauthFormField, RecoveryExpiredContext, RecoveryFinishContext, RecoveryFinishFormField,
+        RecoveryProgressContext, RecoveryStartContext, RecoveryStartFormField, RegisterContext,
+        RegisterFormField, SiteBranding, SiteConfigExt, SiteFeatures, TemplateContext,
+        UpstreamExistingLinkContext, UpstreamRegister, UpstreamRegisterFormField,
+        UpstreamSuggestLink, WithCaptcha, WithCsrf, WithLanguage, WithOptionalSession, WithSession,
     },
     forms::{FieldError, FormError, FormField, FormState, ToFormState},
 };
@@ -324,6 +324,12 @@ register_templates! {
     /// Render the frontend app
     pub fn render_app(WithLanguage<AppContext>) { "app.html" }
 
+    /// Render the Swagger API reference
+    pub fn render_swagger(ApiDocContext) { "swagger/doc.html" }
+
+    /// Render the Swagger OAuth2 callback page
+    pub fn render_swagger_callback(ApiDocContext) { "swagger/oauth2-redirect.html" }
+
     /// Render the login page
     pub fn render_login(WithLanguage<WithCsrf<LoginContext>>) { "pages/login.html" }
 
@@ -423,6 +429,8 @@ impl Templates {
     ) -> anyhow::Result<()> {
         check::render_not_found(self, now, rng)?;
         check::render_app(self, now, rng)?;
+        check::render_swagger(self, now, rng)?;
+        check::render_swagger_callback(self, now, rng)?;
         check::render_login(self, now, rng)?;
         check::render_register(self, now, rng)?;
         check::render_consent(self, now, rng)?;

docs/api/index.html

@@ -0,0 +1,24 @@
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="description" content="SwaggerUI" />
+    <title>API documentation</title>
+    <link rel="stylesheet" href="https://unpkg.com/[email protected]/swagger-ui.css" />
+  </head>
+  <body>
+  <div id="swagger-ui"></div>
+  <script src="https://unpkg.com/[email protected]/swagger-ui-bundle.js" crossorigin></script>
+  <script>
+    window.onload = () => {
+      window.ui = SwaggerUIBundle({
+        url: './spec.json',
+        dom_id: '#swagger-ui',
+        presets: [
+          SwaggerUIBundle.presets.apis,
+        ],
+      });
+    };
+  </script>
+  </body>
+</html>