Enums
GraphQL enum types, like scalar types, also represent leaf values in a GraphQL type system. However enum types describe the set of possible values.
Enums are not references for a numeric value, but are unique values in their own right. They may serialize as a string: the name of the represented value.
With Juniper a GraphQL enum may be defined by using the #[derive(GraphQLEnum)]
attribute on a Rust enum as long as its variants do not have any fields:
extern crate juniper; use juniper::GraphQLEnum; #[derive(GraphQLEnum)] enum Episode { NewHope, Empire, Jedi, } fn main() {}
Renaming
By default, enum variants are converted from Rust's standard PascalCase
naming convention into GraphQL's SCREAMING_SNAKE_CASE
convention:
extern crate juniper; use juniper::GraphQLEnum; #[derive(GraphQLEnum)] enum Episode { NewHope, // exposed as `NEW_HOPE` in GraphQL schema Empire, // exposed as `EMPIRE` in GraphQL schema Jedi, // exposed as `JEDI` in GraphQL schema } fn main() {}
We can override the name by using the #[graphql(name = "...")]
attribute:
extern crate juniper; use juniper::GraphQLEnum; #[derive(GraphQLEnum)] #[graphql(name = "WrongEpisode")] // now exposed as `WrongEpisode` in GraphQL schema enum Episode { #[graphql(name = "LAST_HOPE")] NewHope, // exposed as `LAST_HOPE` in GraphQL schema Empire, Jedi, } fn main() {}
Or provide a different renaming policy for all the enum variants:
extern crate juniper; use juniper::GraphQLEnum; #[derive(GraphQLEnum)] #[graphql(rename_all = "none")] // disables any renaming enum Episode { NewHope, // exposed as `NewHope` in GraphQL schema Empire, // exposed as `Empire` in GraphQL schema Jedi, // exposed as `Jedi` in GraphQL schema } fn main() {}
TIP: Supported policies are:
SCREAMING_SNAKE_CASE
,camelCase
andnone
(disables any renaming).
Documentation and deprecation
Just like when defining GraphQL objects, the GraphQL enum type and its values could be documented and deprecated via #[graphql(description = "...")]
and #[graphql(deprecated = "...")]
/#[deprecated]
attributes:
extern crate juniper; use juniper::GraphQLEnum; /// This doc comment is visible only in Rust API docs. #[derive(GraphQLEnum)] #[graphql(description = "An episode of Star Wars")] enum StarWarsEpisode { /// This doc comment is visible only in Rust API docs. #[graphql(description = "This description is visible only in GraphQL schema.")] NewHope, /// This doc comment is visible only in Rust API docs. #[graphql(desc = "Arguably the best one in the trilogy.")] // ^^^^ shortcut for a `description` argument Empire, /// This doc comment is visible in both Rust API docs and GraphQL schema /// descriptions. Jedi, #[deprecated(note = "Only visible in Rust.")] #[graphql(deprecated = "We don't really talk about this one.")] // ^^^^^^^^^^ takes precedence over Rust's `#[deprecated]` attribute ThePhantomMenace, // has no description in GraphQL schema } fn main() {}
NOTE: Only GraphQL object/interface fields and GraphQL enum values can be deprecated.
Ignoring
By default, all enum variants are included in the generated GraphQL enum type as values. To prevent including a specific variant, annotate it with the #[graphql(ignore)]
attribute:
#![allow(dead_code)] extern crate juniper; use juniper::GraphQLEnum; #[derive(GraphQLEnum)] enum Episode<T> { NewHope, Empire, Jedi, #[graphql(ignore)] Legends(T), // cannot be queried from GraphQL #[graphql(skip)] // ^^^^ alternative naming, up to your preference CloneWars(T), // cannot be queried from GraphQL } fn main() {}
TIP: See more available features in the API docs of the
#[derive(GraphQLEnum)]
attribute.