cynic_introspection/lib.rs
1#![deny(missing_docs)]
2//! `cynic-introspection` defines a [GraphQL introspection query][1] that can be
3//! run using [`cynic`][2], a rust GraphQL client.
4//!
5//! This can be used for any reason you'd want to introspect a GraphQL server -
6//! including when you're using cynic as a library in your own project.
7//!
8//! It also provides a [Schema] abstraction on top of the introspection query
9//! results, which provides some stronger typing than using the introspection
10//! results directly.
11//!
12//! ```rust
13//! use cynic::{QueryBuilder, http::ReqwestExt};
14//! use cynic_introspection::IntrospectionQuery;
15//! # #[tokio::main]
16//! # async fn main() {
17//! # let server = graphql_mocks::mocks::swapi::serve().await;
18//! # let url = server.url();
19//! # let url = url.as_ref();
20//!
21//! // We can run an introspection query and unwrap the data contained within
22//! let introspection_data = reqwest::Client::new()
23//! .post(url)
24//! .run_graphql(IntrospectionQuery::build(()))
25//! .await
26//! .unwrap()
27//! .data
28//! .unwrap();
29//!
30//! // And then convert it into a schema for easier use.
31//! let schema = introspection_data.into_schema().unwrap();
32//!
33//! assert_eq!(schema.query_type, "Root");
34//! # }
35//! ```
36//!
37//! ### GraphQL Versions
38//!
39//! GraphQL servers currently commonly support two different versions of the GraphQL
40//! specification:
41//!
42//! - [The June 2018 Specification][3]
43//! - [The October 2021 Specification][4]
44//!
45//! The fields available for introspection differ between these two versions. By default
46//! we query only for fields supported in the June 2018 specification. You can request
47//! a different version of the query using [InstrospectionQuery::with_capabilities]:
48//!
49//! ```rust
50//! use cynic::http::ReqwestBlockingExt;
51//! use cynic_introspection::{IntrospectionQuery, SpecificationVersion};
52//!
53//! // We can run an introspection query and unwrap the data contained within
54//! let introspection_data = reqwest::blocking::Client::new()
55//! .post("https://spacex-production.up.railway.app/")
56//! .run_graphql(
57//! IntrospectionQuery::with_capabilities(
58//! SpecificationVersion::October2021.capabilities()
59//! )
60//! )
61//! .unwrap()
62//! .data
63//! .unwrap();
64//!
65//! // And then convert it into a schema for easier use.
66//! let schema = introspection_data.into_schema().unwrap();
67//!
68//! assert_eq!(schema.query_type, "Query");
69//! ```
70//!
71//! ### Detecting Capabilities
72//!
73//! `cynic-introspection` also provides [CapabilitiesQuery], a query which can
74//! determine the capabilites of a remote GraphQL server. This can be paired with
75//! `Introspection::with_capabilities`:
76//!
77//! ```rust
78//! use cynic::{QueryBuilder, http::ReqwestExt};
79//! use cynic_introspection::{CapabilitiesQuery, IntrospectionQuery};
80//! # #[tokio::main]
81//! # async fn main() {
82//! # let server = graphql_mocks::mocks::swapi::serve().await;
83//! # let url = server.url();
84//! # let url = url.as_ref();
85//!
86//! // First we run a capabilites query to check what the server supports
87//! let capabilities = reqwest::Client::new()
88//! .post(url)
89//! .run_graphql(CapabilitiesQuery::build(()))
90//! .await
91//! .unwrap()
92//! .data
93//! .unwrap()
94//! .capabilities();
95//!
96//! // Now we can safely run introspection, only querying for what the server supports.
97//! let introspection_data = reqwest::Client::new()
98//! .post(url)
99//! .run_graphql(IntrospectionQuery::with_capabilities(capabilities))
100//! .await
101//! .unwrap()
102//! .data
103//! .unwrap();
104//!
105//! // And then convert it into a schema for easier use.
106//! let schema = introspection_data.into_schema().unwrap();
107//!
108//! assert_eq!(schema.query_type, "Root");
109//! # }
110//! ```
111//!
112//! [1]: http://spec.graphql.org/October2021/#sec-Introspection
113//! [2]: https://cynic-rs.dev
114//! [3]: http://spec.graphql.org/June2018
115//! [4]: http://spec.graphql.org/October2021
116
117mod capabilities;
118mod detection;
119pub mod query;
120mod query_builder;
121mod schema;
122
123pub use capabilities::CapabilitySet;
124#[doc(inline)]
125pub use detection::{CapabilitiesQuery, SpecificationVersion};
126#[doc(inline)]
127pub use query::{DirectiveLocation, IntrospectionQuery};
128
129pub use schema::*;