Skip to content
This repository was archived by the owner on Sep 10, 2024. It is now read-only.

Commit f382846

Browse files
sandhosesandhose
committed
Merge branch 'quenting/admin-api/doc' into quenting/admin-api/temp-merge-base
2 parents 82ce8a7 + f1bf85e commit f382846

File tree

5 files changed

+116
-92
lines changed

5 files changed

+116
-92
lines changed

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

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,7 @@ mod call_context;
3939
mod model;
4040
mod params;
4141
mod response;
42+
mod schema;
4243
mod v1;
4344

4445
use self::call_context::CallContext;
@@ -52,6 +53,10 @@ where
5253
Templates: FromRef<S>,
5354
UrlBuilder: FromRef<S>,
5455
{
56+
aide::gen::in_context(|ctx| {
57+
ctx.schema = schemars::gen::SchemaGenerator::new(schemars::gen::SchemaSettings::openapi3());
58+
});
59+
5560
let mut api = OpenApi::default();
5661
let router = ApiRouter::<S>::new()
5762
.nest("/api/admin/v1", self::v1::router())

‎crates/handlers/src/admin/params.rs‎

Lines changed: 4 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -52,12 +52,8 @@ impl IntoResponse for UlidPathParamRejection {
5252

5353
#[derive(JsonSchema, Debug, Clone, Copy, Deserialize)]
5454
struct UlidInPath {
55-
#[schemars(
56-
with = "String",
57-
title = "ULID",
58-
description = "A ULID as per https://github.com/ulid/spec",
59-
regex(pattern = r"^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$")
60-
)]
55+
/// # The ID of the resource
56+
#[schemars(with = "super::schema::Ulid")]
6157
id: Ulid,
6258
}
6359

@@ -81,12 +77,12 @@ const DEFAULT_PAGE_SIZE: usize = 10;
8177
struct PaginationParams {
8278
/// Retrieve the items before the given ID
8379
#[serde(rename = "page[before]")]
84-
#[schemars(with = "Option<String>")]
80+
#[schemars(with = "Option<super::schema::Ulid>")]
8581
before: Option<Ulid>,
8682

8783
/// Retrieve the items after the given ID
8884
#[serde(rename = "page[after]")]
89-
#[schemars(with = "Option<String>")]
85+
#[schemars(with = "Option<super::schema::Ulid>")]
9086
after: Option<Ulid>,
9187

9288
/// Retrieve the first N items

‎crates/handlers/src/admin/response.rs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -143,7 +143,7 @@ struct SingleResource<T> {
143143
type_: &'static str,
144144

145145
/// The ID of the resource
146-
#[schemars(with = "String")]
146+
#[schemars(with = "super::schema::Ulid")]
147147
id: Ulid,
148148

149149
/// The attributes of the resource

‎crates/handlers/src/admin/schema.rs‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
// Copyright 2024 The Matrix.org Foundation C.I.C.
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// http://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
15+
//! Common schema definitions
16+
17+
use schemars::{
18+
gen::SchemaGenerator,
19+
schema::{InstanceType, Metadata, Schema, SchemaObject, StringValidation},
20+
JsonSchema,
21+
};
22+
23+
/// A type to use for schema definitions of ULIDs
24+
///
25+
/// Use with `#[schemars(with = "crate::admin::schema::Ulid")]`
26+
pub struct Ulid;
27+
28+
impl JsonSchema for Ulid {
29+
fn schema_name() -> String {
30+
"ULID".to_owned()
31+
}
32+
33+
fn json_schema(_gen: &mut SchemaGenerator) -> Schema {
34+
SchemaObject {
35+
instance_type: Some(InstanceType::String.into()),
36+
37+
metadata: Some(Box::new(Metadata {
38+
title: Some("ULID".into()),
39+
description: Some("A ULID as per https://github.com/ulid/spec".into()),
40+
examples: vec![
41+
"01ARZ3NDEKTSV4RRFFQ69G5FAV".into(),
42+
"01J41912SC8VGAQDD50F6APK91".into(),
43+
],
44+
..Metadata::default()
45+
})),
46+
47+
string: Some(Box::new(StringValidation {
48+
pattern: Some(r"^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$".into()),
49+
..StringValidation::default()
50+
})),
51+
52+
..SchemaObject::default()
53+
}
54+
.into()
55+
}
56+
}

‎docs/api/spec.json‎

Lines changed: 50 additions & 83 deletions
Original file line numberDiff line numberDiff line change
@@ -29,10 +29,8 @@
2929
"description": "Retrieve the items before the given ID",
3030
"schema": {
3131
"description": "Retrieve the items before the given ID",
32-
"type": [
33-
"string",
34-
"null"
35-
]
32+
"$ref": "#/components/schemas/ULID",
33+
"nullable": true
3634
},
3735
"style": "form"
3836
},
@@ -42,10 +40,8 @@
4240
"description": "Retrieve the items after the given ID",
4341
"schema": {
4442
"description": "Retrieve the items after the given ID",
45-
"type": [
46-
"string",
47-
"null"
48-
]
43+
"$ref": "#/components/schemas/ULID",
44+
"nullable": true
4945
},
5046
"style": "form"
5147
},
@@ -55,12 +51,10 @@
5551
"description": "Retrieve the first N items",
5652
"schema": {
5753
"description": "Retrieve the first N items",
58-
"type": [
59-
"integer",
60-
"null"
61-
],
54+
"type": "integer",
6255
"format": "uint",
63-
"minimum": 1.0
56+
"minimum": 1.0,
57+
"nullable": true
6458
},
6559
"style": "form"
6660
},
@@ -70,38 +64,28 @@
7064
"description": "Retrieve the last N items",
7165
"schema": {
7266
"description": "Retrieve the last N items",
73-
"type": [
74-
"integer",
75-
"null"
76-
],
67+
"type": "integer",
7768
"format": "uint",
78-
"minimum": 1.0
69+
"minimum": 1.0,
70+
"nullable": true
7971
},
8072
"style": "form"
8173
},
8274
{
8375
"in": "query",
8476
"name": "filter[can_request_admin]",
8577
"schema": {
86-
"type": [
87-
"boolean",
88-
"null"
89-
]
78+
"type": "boolean",
79+
"nullable": true
9080
},
9181
"style": "form"
9282
},
9383
{
9484
"in": "query",
9585
"name": "filter[status]",
9686
"schema": {
97-
"anyOf": [
98-
{
99-
"$ref": "#/components/schemas/UserStatus"
100-
},
101-
{
102-
"type": "null"
103-
}
104-
]
87+
"$ref": "#/components/schemas/UserStatus",
88+
"nullable": true
10589
},
10690
"style": "form"
10791
}
@@ -262,13 +246,10 @@
262246
{
263247
"in": "path",
264248
"name": "id",
265-
"description": "A ULID as per https://github.com/ulid/spec",
266249
"required": true,
267250
"schema": {
268-
"title": "ULID",
269-
"description": "A ULID as per https://github.com/ulid/spec",
270-
"type": "string",
271-
"pattern": "^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$"
251+
"title": "The ID of the resource",
252+
"$ref": "#/components/schemas/ULID"
272253
},
273254
"style": "simple"
274255
}
@@ -420,56 +401,50 @@
420401
"properties": {
421402
"page[before]": {
422403
"description": "Retrieve the items before the given ID",
423-
"type": [
424-
"string",
425-
"null"
426-
]
404+
"$ref": "#/components/schemas/ULID",
405+
"nullable": true
427406
},
428407
"page[after]": {
429408
"description": "Retrieve the items after the given ID",
430-
"type": [
431-
"string",
432-
"null"
433-
]
409+
"$ref": "#/components/schemas/ULID",
410+
"nullable": true
434411
},
435412
"page[first]": {
436413
"description": "Retrieve the first N items",
437-
"type": [
438-
"integer",
439-
"null"
440-
],
414+
"type": "integer",
441415
"format": "uint",
442-
"minimum": 1.0
416+
"minimum": 1.0,
417+
"nullable": true
443418
},
444419
"page[last]": {
445420
"description": "Retrieve the last N items",
446-
"type": [
447-
"integer",
448-
"null"
449-
],
421+
"type": "integer",
450422
"format": "uint",
451-
"minimum": 1.0
423+
"minimum": 1.0,
424+
"nullable": true
452425
}
453426
}
454427
},
428+
"ULID": {
429+
"title": "ULID",
430+
"description": "A ULID as per https://github.com/ulid/spec",
431+
"examples": [
432+
"01ARZ3NDEKTSV4RRFFQ69G5FAV",
433+
"01J41912SC8VGAQDD50F6APK91"
434+
],
435+
"type": "string",
436+
"pattern": "^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$"
437+
},
455438
"FilterParams": {
456439
"type": "object",
457440
"properties": {
458441
"filter[can_request_admin]": {
459-
"type": [
460-
"boolean",
461-
"null"
462-
]
442+
"type": "boolean",
443+
"nullable": true
463444
},
464445
"filter[status]": {
465-
"anyOf": [
466-
{
467-
"$ref": "#/components/schemas/UserStatus"
468-
},
469-
{
470-
"type": "null"
471-
}
472-
]
446+
"$ref": "#/components/schemas/UserStatus",
447+
"nullable": true
473448
}
474449
}
475450
},
@@ -547,7 +522,7 @@
547522
},
548523
"id": {
549524
"description": "The ID of the resource",
550-
"type": "string"
525+
"$ref": "#/components/schemas/ULID"
551526
},
552527
"attributes": {
553528
"description": "The attributes of the resource",
@@ -579,11 +554,9 @@
579554
},
580555
"locked_at": {
581556
"description": "When the user was locked. If null, the user is not locked.",
582-
"type": [
583-
"string",
584-
"null"
585-
],
586-
"format": "date-time"
557+
"type": "string",
558+
"format": "date-time",
559+
"nullable": true
587560
},
588561
"can_request_admin": {
589562
"description": "Whether the user can request admin privileges.",
@@ -627,17 +600,13 @@
627600
},
628601
"next": {
629602
"description": "The link to the next page of results\n\nOnly present if there is a next page",
630-
"type": [
631-
"string",
632-
"null"
633-
]
603+
"type": "string",
604+
"nullable": true
634605
},
635606
"prev": {
636607
"description": "The link to the previous page of results\n\nOnly present if there is a previous page",
637-
"type": [
638-
"string",
639-
"null"
640-
]
608+
"type": "string",
609+
"nullable": true
641610
}
642611
}
643612
},
@@ -711,10 +680,8 @@
711680
],
712681
"properties": {
713682
"id": {
714-
"title": "ULID",
715-
"description": "A ULID as per https://github.com/ulid/spec",
716-
"type": "string",
717-
"pattern": "^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$"
683+
"title": "The ID of the resource",
684+
"$ref": "#/components/schemas/ULID"
718685
}
719686
}
720687
},

0 commit comments

Comments
 (0)