Skip to content

Commit eec04b4

Browse files
authored
controllers/keyword: Add query params documentation (#10684)
1 parent c960e25 commit eec04b4

File tree

2 files changed

+56
-6
lines changed

2 files changed

+56
-6
lines changed

src/controllers/keyword.rs

Lines changed: 14 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,37 +1,45 @@
11
use crate::app::AppState;
2-
use crate::controllers::helpers::pagination::PaginationOptions;
2+
use crate::controllers::helpers::pagination::{PaginationOptions, PaginationQueryParams};
33
use crate::controllers::helpers::{Paginate, pagination::Paginated};
44
use crate::models::Keyword;
55
use crate::util::errors::AppResult;
66
use crate::views::EncodableKeyword;
7-
use axum::extract::{Path, Query};
7+
use axum::extract::{FromRequestParts, Path, Query};
88
use axum_extra::json;
99
use axum_extra::response::ErasedJson;
1010
use diesel::prelude::*;
1111
use http::request::Parts;
1212

13-
#[derive(Deserialize)]
14-
pub struct IndexQuery {
13+
#[derive(Debug, Deserialize, FromRequestParts, utoipa::IntoParams)]
14+
#[from_request(via(Query))]
15+
#[into_params(parameter_in = Query)]
16+
pub struct ListQueryParams {
17+
/// The sort order of the keywords.
18+
///
19+
/// Valid values: `alpha`, and `crates`.
20+
///
21+
/// Defaults to `alpha`.
1522
sort: Option<String>,
1623
}
1724

1825
/// List all keywords.
1926
#[utoipa::path(
2027
get,
2128
path = "/api/v1/keywords",
29+
params(ListQueryParams, PaginationQueryParams),
2230
tag = "keywords",
2331
responses((status = 200, description = "Successful Response")),
2432
)]
2533
pub async fn list_keywords(
2634
state: AppState,
27-
qp: Query<IndexQuery>,
35+
params: ListQueryParams,
2836
req: Parts,
2937
) -> AppResult<ErasedJson> {
3038
use crate::schema::keywords;
3139

3240
let mut query = keywords::table.into_boxed();
3341

34-
query = match &qp.sort {
42+
query = match &params.sort {
3543
Some(sort) if sort == "crates" => query.order(keywords::crates_cnt.desc()),
3644
_ => query.order(keywords::keyword.asc()),
3745
};

src/snapshots/crates_io__openapi__tests__openapi_snapshot.snap

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1287,6 +1287,48 @@ expression: response.json()
12871287
"/api/v1/keywords": {
12881288
"get": {
12891289
"operationId": "list_keywords",
1290+
"parameters": [
1291+
{
1292+
"description": "The sort order of the keywords.\n\nValid values: `alpha`, and `crates`.\n\nDefaults to `alpha`.",
1293+
"in": "query",
1294+
"name": "sort",
1295+
"required": false,
1296+
"schema": {
1297+
"type": "string"
1298+
}
1299+
},
1300+
{
1301+
"description": "The page number to request.\n\nThis parameter is mutually exclusive with `seek` and not supported for\nall requests.",
1302+
"in": "query",
1303+
"name": "page",
1304+
"required": false,
1305+
"schema": {
1306+
"format": "int32",
1307+
"minimum": 1,
1308+
"type": "integer"
1309+
}
1310+
},
1311+
{
1312+
"description": "The number of items to request per page.",
1313+
"in": "query",
1314+
"name": "per_page",
1315+
"required": false,
1316+
"schema": {
1317+
"format": "int32",
1318+
"minimum": 1,
1319+
"type": "integer"
1320+
}
1321+
},
1322+
{
1323+
"description": "The seek key to request.\n\nThis parameter is mutually exclusive with `page` and not supported for\nall requests.\n\nThe seek key can usually be found in the `meta.next_page` field of\npaginated responses.",
1324+
"in": "query",
1325+
"name": "seek",
1326+
"required": false,
1327+
"schema": {
1328+
"type": "string"
1329+
}
1330+
}
1331+
],
12901332
"responses": {
12911333
"200": {
12921334
"description": "Successful Response"

0 commit comments

Comments
 (0)