Attribute Macro async_graphql::Object

#[Object]

Define a GraphQL object with methods

See also the Book.

All methods are converted to camelCase.

Macro parameters

Attribute	description	Type	Optional
name	Object name	string	Y
desc	Object description	string	Y
cache_control	Object cache control	CacheControl	Y
extends	Add fields to an entity that's defined in another service	bool	Y

Field parameters

Attribute	description	Type	Optional
name	Field name	string	Y
desc	Field description	string	Y
deprecation	Field deprecation reason	string	Y
cache_control	Field cache control	CacheControl	Y
external	Mark a field as owned by another service. This allows service A to use fields from service B while also knowing at runtime the types of that field.	bool	Y
provides	Annotate the expected returned fieldset from a field on a base type that is guaranteed to be selectable by the gateway.	string	Y
requires	Annotate the required input fieldset from a base type for a resolver. It is used to develop a query plan where the required fields may not be needed by the client, but the service may need additional information from other services.	string	Y
guard	Field of guard	Guard	Y
feature	It's like a #[cfg(feature = "foo")] attribute but instead of not compiling this field it will just return a proper FieldError to tell you this feature is not enabled	string ("feature1,feature2")	Y

Field argument parameters

Attribute	description	Type	Optional
name	Argument name	string	Y
desc	Argument description	string	Y
default	Use Default::default for default value	none	Y
default	Argument default value	literal	Y
default_with	Expression to generate default value	code string	Y
validator	Input value validator	InputValueValidator	Y

Valid field return types

• Scalar values, such as i32 and bool. usize, isize, u128 and i128 are not supported
• Vec<T>, such as Vec<i32>
• Slices, such as &[i32]
• Option<T>, such as Option<i32>
• GraphQL objects.
• GraphQL enums.
• References to any of the above types, such as &i32 or &Option<String>.
• FieldResult<T, E>, such as FieldResult<i32, E>

Context

You can define a context as an argument to a method, and the context should be the first argument to the method.

#[Object]
impl QueryRoot {
    async fn value(&self, ctx: &Context<'_>) -> { ... }
}

Examples

use async_graphql::*;

struct QueryRoot {
    value: i32,
}

#[Object]
impl QueryRoot {
    #[field(desc = "value")]
    async fn value(&self) -> i32 {
        self.value
    }

    #[field(desc = "reference value")]
    async fn value_ref(&self) -> &i32 {
        &self.value
    }

    #[field(desc = "value with error")]
    async fn value_with_error(&self) -> FieldResult<i32> {
        Ok(self.value)
    }

    async fn value_with_arg(&self, #[arg(default = 1)] a: i32) -> i32 {
        a
    }
}

async_std::task::block_on(async move {
    let schema = Schema::new(QueryRoot { value: 10 }, EmptyMutation, EmptySubscription);
    let res = schema.execute(r#"{
        value
        valueRef
        valueWithError
        valueWithArg1: valueWithArg
        valueWithArg2: valueWithArg(a: 99)
    }"#).await.into_result().unwrap().data;
    assert_eq!(res, serde_json::json!({
        "value": 10,
        "valueRef": 10,
        "valueWithError": 10,
        "valueWithArg1": 1,
        "valueWithArg2": 99
    }));
});