Tweak the schema generation and use a common definition for ULIDs

crates/handlers/src/admin/mod.rs

@@ -37,6 +37,7 @@ mod call_context;
 mod model;
 mod params;
 mod response;
+mod schema;
 mod v1;
 
 use self::call_context::CallContext;
@@ -48,6 +49,10 @@ where
     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())

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()
+    }
+}