17 releases
0.5.0-rc.2 | Nov 23, 2024 |
---|---|
0.5.0-rc.1 | Jun 2, 2024 |
0.4.2 | Jan 23, 2024 |
0.4.1 | Dec 21, 2023 |
0.2.2 | Nov 15, 2021 |
#581 in Web programming
309 downloads per month
Used in mwbot
70KB
744 lines
mwapi_responses
The mwapi_responses
crate provides strict typing for dynamic MediaWiki
Action API queries. The goal is to faithfully represent what the API's
JSON structure is while saving people from manually writing out
serde-compatible structs for every query.
A list module:
use mwapi_responses::prelude::*;
#[query(
list = "logevents",
leaction = "newusers/create",
leprop = "user|type",
lelimit = "100"
)]
struct Response;
This creates a Response
struct that matches the API response for the given
query. Roughly, it will expand to:
#[derive(Debug, Clone, serde::Deserialize)]
pub struct Response {
#[serde(default)]
pub batchcomplete: bool,
#[serde(rename = "continue")]
#[serde(default)]
pub continue_: HashMap<String, String>,
pub query: ResponseBody,
}
#[derive(Debug, Clone, serde::Deserialize)]
pub struct ResponseBody {
pub logevents: Vec<ResponseItemlogevents>,
}
#[derive(Debug, Clone, serde::Deserialize)]
pub struct ResponseItemlogevents {
pub user: String,
#[serde(rename = "type")]
pub type_: String,
}
Or getting various properties from pages:
use mwapi_responses::prelude::*;
#[query(
prop="info|revisions",
inprop="url",
rvprop="ids"
)]
struct Response;
which expands to:
#[derive(Debug, Clone, serde::Deserialize)]
pub struct Response {
#[serde(default)]
pub batchcomplete: bool,
#[serde(rename = "continue")]
#[serde(default)]
pub continue_: HashMap<String, String>,
pub query: ResponseBody,
}
#[derive(Debug, Clone, serde::Deserialize)]
pub struct ResponseBody {
pub pages: Vec<ResponseItem>,
}
#[derive(Debug, Clone, serde::Deserialize)]
pub struct ResponseItem {
pub canonicalurl: String,
pub contentmodel: String,
pub editurl: String,
pub fullurl: String,
pub lastrevid: Option<u64>,
pub length: Option<u32>,
#[serde(default)]
pub missing: bool,
#[serde(default)]
pub new: bool,
pub ns: i32,
pub pageid: Option<u32>,
pub pagelanguage: String,
pub pagelanguagedir: String,
pub pagelanguagehtmlcode: String,
#[serde(default)]
pub redirect: bool,
pub title: String,
pub touched: Option<String>,
#[serde(default)]
pub revisions: Vec<ResponseItemrevisions>,
}
#[derive(Debug, Clone, serde::Deserialize)]
pub struct ResponseItemrevisions {
pub parentid: u64,
pub revid: u64,
}
In both cases, you can easily iterate over ResponseItemlogevents
and ResponseItem
respectively by calling Response::items()
.
To avoid repeating the parameters in multiple places, you can call
Response::params()
to get a &[(&str, &str)]
of the parameters that
were provided to the #[query(...)]
macro.
Fields are renamed if they can't be used as fields in Rust, like continue
or type
. In these cases, an underscore is appended.
Supported modules
The metadata that powers this crate is manually gathered. To see if a specific module is supported, look at the Git repository. Contributions for missing modules or parameters are always welcome.
Library agnostic
This crate does not implement or support any one specific API or HTTP library, rather it aims to just provide types and helpers to enable you to run and execute your API requests however you'd like.
The mwapi
crate provides a convenience function
to execute a query using these generated responses: query_response()
.
Future plans
There is no special support for continuing queries. In the future some merge()-like function might be provided.
Some other ideas are outlined in a blog post by Legoktm.
Contributing
mwapi_responses
is a part of the mwbot-rs
project.
We're always looking for new contributors, please reach out
if you're interested!
License
This crate is released under GPL-3.0-or-later. See COPYING for details.
Dependencies
~1–13MB
~153K SLoC