1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281
//! # Cynic //! //! Cynic is a GraphQL query builder & data mapper for Rust. //! //! This documentation is primarily intended to be a reference for specific functions, //! for a guide to using `Cynic` see the website: [cynic-rs.dev](https://cynic-rs.dev). //! //! ## Overview //! //! To get started with Cynic you'll need a GraphQL schema for the API you wish to //! query. The examples will be using the star wars API. //! //! ### Generating a Query DSL //! //! Once you've got your schema installed locally, you'll need to use the //! `query_dsl` macro to generate a query_dsl for your schema: //! //! ```rust //! mod query_dsl { //! cynic::query_dsl!("../examples/examples/starwars.schema.graphql"); //! } //! ``` //! //! This macro generates a few things: //! //! 1. Some structs to represent the Input types the underlying schema. //! You may need to use these to build mutations or as parameters to queries. //! 2. Definitons of all the Enums in the provided schema. You'll need these if //! you want to use any enum types. //! 3. Type safe selection set functions. These can be used to build up a query //! manually, though it's usually easier to use the `QueryFragment` derive //! functionality explained below. Hopefully you'll not need to use these //! directly too often. //! //! Though using macros to generate these is convenient, it does leave a lot of code //! to the imagination. You can get a glimpse of the things this defines by running //! `cargo doc --document-private-items` and having a look in the `query_dsl` module. //! It's not ideal, but at least provides some visibility into the various enum types. //! //! ### Creating QueryFragments //! //! Now that you have a query_dsl defined, you can start building some queries. //! Cynic lets you do this by deriving `QueryFragment` for a struct. For example, //! if we wanted to know what director title & director a Star Wars film had, we //! could define this `QueryFragment`: //! //! ```rust //! # mod query_dsl { //! # cynic::query_dsl!("../examples/examples/starwars.schema.graphql"); //! # } //! //! #[derive(cynic::QueryFragment)] //! #[cynic( //! schema_path = "../examples/examples/starwars.schema.graphql", //! query_module = "query_dsl", //! graphql_type = "Film" //! )] //! struct Film { //! title: Option<String>, //! director: Option<String> //! } //! //! // This `Film` struct can now be used as the type of a field on any other //! // `QueryFragment` struct and cynic will know how to turn that into a GraphQL //! // query, and populate the `Film` struct from the response. //! //! // For example, if we wanted to know the Director for a particular film: //! //! #[derive(cynic::QueryFragment)] //! #[cynic( //! schema_path = "../examples/examples/starwars.schema.graphql", //! query_module = "query_dsl", //! graphql_type = "Root" //! )] //! struct FilmDirectorQuery { //! // Here we use the `#[arguments()]` attribute on the `film` field to provide a //! // hard coded film ID to look up. Though useful for demonstration, hard coded //! // arguments like this aren't much use in reality. For more details on providing //! // runtime arguments please see below. //! #[arguments(id = cynic::Id::new("ZmlsbXM6MQ=="))] //! film: Option<Film>, //! } //! //! // You can then build a `cynic::Query` from this fragment //! use cynic::QueryFragment; //! let operation = cynic::Operation::query(FilmDirectorQuery::fragment(())); //! //! ``` //! //! `operation` above implements `serde::Serialize` so can be used with any HTTP //! client. For example, with `reqwest`: //! //! ```rust,ignore //! let response = reqwest::blocking::Client::new() //! .post("a_url") //! .json(&operation) //! .send()?; //! let result = query.decode_response(response.json()?)?; //! ``` //! //! After this code has run, result will be an instance of `FilmDirectorQuery` //! with the film populated appropriately. //! //! ### Dynamic Query Arguments //! //! The query above was useful for demonstration, but you'll usually want to be able to //! provide parameters to your query. To do this, you should define a struct that contains //! all of the parameters you want to provide: //! //! ```rust //! # mod query_dsl { //! # cynic::query_dsl!("../examples/examples/starwars.schema.graphql"); //! # } //! //! # #[derive(cynic::QueryFragment)] //! # #[cynic( //! # schema_path = "../examples/examples/starwars.schema.graphql", //! # query_module = "query_dsl", //! # graphql_type = "Film" //! # )] //! # struct Film { //! # title: Option<String>, //! # director: Option<String> //! # } //! // Deriving `FragmentArguments` allows this struct to be used as arguments to a //! // `QueryFragment` fragment, whether it represents part of a query or a whole query. //! #[derive(cynic::FragmentArguments, Clone)] //! struct FilmArguments { //! id: Option<cynic::Id> //! } //! //! // You can now define a query to use these arguments on. For example, to make //! // `FilmDirectorQuery` a bit more dynamic: //! #[derive(cynic::QueryFragment)] //! #[cynic( //! schema_path = "../examples/examples/starwars.schema.graphql", //! query_module = "query_dsl", //! graphql_type = "Root", //! // By adding the `argument_struct` parameter to our `QueryFragment` we've made a variable //! // named `args` avaiable for use in the `arguments` attribute. //! argument_struct = "FilmArguments" //! )] //! struct FilmDirectorQueryWithArgs { //! // Here we use `args`, which we've declared above to be an instance of `FilmArguments` //! #[arguments(id = args.id.clone())] //! film: Option<Film>, //! } //! //! // Then we can build a query using this new struct; //! use cynic::QueryFragment; //! let operation = cynic::Operation::query( //! FilmDirectorQueryWithArgs::fragment( //! FilmArguments{ id: Some("ZmlsbXM6MQ==".into()) } //! ) //! ); //! ``` mod argument; mod field; mod id; mod into_argument; mod operation; mod result; mod scalar; pub mod selection_set; pub mod utils; pub use json_decode::DecodeError; pub use argument::{Argument, SerializableArgument}; pub use id::Id; pub use operation::Operation; pub use result::{GraphQLError, GraphQLResponse, GraphQLResult, PossiblyParsedData}; pub use scalar::Scalar; pub use selection_set::SelectionSet; pub use into_argument::IntoArgument; pub trait QueryFragment { type SelectionSet; type Arguments: FragmentArguments; fn fragment(arguments: Self::Arguments) -> Self::SelectionSet; fn graphql_type() -> String; } pub trait InlineFragments: Sized { type TypeLock; type Arguments: FragmentArguments; fn graphql_type() -> String; fn fragments( arguments: Self::Arguments, ) -> Vec<(String, SelectionSet<'static, Self, Self::TypeLock>)>; } impl<T> QueryFragment for T where T: InlineFragments + Send + Sync + 'static, { type SelectionSet = SelectionSet<'static, T, T::TypeLock>; type Arguments = <T as InlineFragments>::Arguments; fn fragment(arguments: Self::Arguments) -> Self::SelectionSet { selection_set::inline_fragments(Self::fragments(arguments)) } fn graphql_type() -> String { Self::graphql_type() } } pub type SerializeError = Box<dyn std::error::Error>; /// A trait for GraphQL enums. /// /// This trait is generic over some TypeLock which is used to tie an Enum /// definition back into it's GraphQL enum. Generally this will be some /// type generated in the GQL code. pub trait Enum<TypeLock>: Sized { fn select() -> SelectionSet<'static, Self, ()>; } /// A trait for GraphQL input objects. /// /// This trait is generic over some TypeLock which is used to tie an InputType /// back into it's GraphQL input object. Generally this will be some type /// generated in the GQL code. /// /// It's recommended to derive this trait with the [InputObject](derive.InputObject.html) /// derive. You can also implement it yourself, but you'll be responsible /// for implementing the `SerializableArgument` trait if you want to use it. pub trait InputObject<TypeLock>: Clone {} /// A marker trait for the arguments types on QueryFragments. /// /// We use this in combination with the IntoArguments trait below /// to convert between different argument types in a query heirarchy. pub trait FragmentArguments: Clone {} impl FragmentArguments for () {} /// Used for converting between different argument types in a QueryFragment /// heirarchy. /// /// For example if an outer QueryFragment has a struct with several parameters /// but an inner QueryFragment needs none then we can use () as the arguments /// type on the inner fragments and use the blanket implementation of IntoArguments /// to convert to (). pub trait FromArguments<T> { fn from_arguments(args: &T) -> Self; } impl<T> FromArguments<T> for T where T: Clone + FragmentArguments, { fn from_arguments(other: &T) -> Self { // TODO: Figure out if there's a way to avoid this clone... other.clone() } } /// A marker trait that indicates a particular type is at the root of a GraphQL schemas query /// heirarchy. pub trait QueryRoot {} /// A marker trait that indicates a particular type is at the root of a GraphQL schemas /// mutation heirarchy. pub trait MutationRoot {} pub use cynic_proc_macros::{ query_dsl, query_module, Enum, FragmentArguments, InlineFragments, InputObject, QueryFragment, Scalar, }; // We re-export serde_json as the output from a lot of our derive macros require it, // and this way we can point at our copy rather than forcing users to add it to // their Cargo.toml pub use serde_json;