GraphiQL

GraphQL schema introspection is enabled by default in necrassrs::execute. It returns metadata from the validated Reed schema through __schema and __type, including the supported generated schema’s fields, arguments, and type references. __typename remains available as part of ordinary GraphQL execution.

An application may disable schema introspection for a handler with execute_with_options:

use necrassrs::{ExecutionOptions, execute_with_options};

let response = execute_with_options(
    &state.schema,
    &request,
    &state.dispatcher,
    &context,
    ExecutionOptions { introspection: false },
).await;

The application chooses this server-side setting. A disabled __schema or __type selection returns a GraphQL request error without invoking application resolvers. Disabling introspection does not replace authentication or field-level authorization.

Built-in pages and application-owned routes

Register the page only where it should be available. The application still owns the route, GraphQL handler, and per-request Context:

use axum::{Router, middleware, routing::get};
use necrassrs_axum::{graphiql_html, negotiate_response};

let app = Router::new().route("/graphql",
    get(graphql).post(graphql).route_layer(middleware::from_fn(negotiate_response)));
let app = if development {
    app.route("/graphiql", get(|| async { graphiql_html("/graphql") }))
} else {
    app
};

graphiql_html(endpoint_url) sets the URL used for both schema introspection and ordinary GraphQL requests. A same-origin path such as /graphql needs no additional CORS setup. An absolute URL on another origin requires that endpoint to permit browser cross-origin requests. The helper only returns an HTML response; it does not create another GraphQL endpoint or server.

The page loads version-pinned GraphiQL, React, and GraphQL modules and the GraphiQL stylesheet from https://esm.sh. These assets are not bundled with the Rust crate, so the browser needs access to that CDN. A restrictive Content Security Policy must allow the relevant styles, scripts, and workers. The application may instead serve its own page if offline assets are required.

The axum-server example and projects created by necrass init serve GraphiQL on GET /graphiql by default. The page sends requests to /graphql, which accepts GET queries and POST requests. Remove or gate the /graphiql handler before deployment when the UI should be unavailable. This route choice is independent of introspection: the runtime allows introspection by default. An application that wants production introspection disabled must use execute_with_options in its GraphQL handler.

Actix provides the same built-in page through necrassrs_actix::graphiql_html. Register an application-owned UI route separately from its GraphQL endpoint:

use actix_web::{App, web};
use necrassrs_actix::graphiql_html;

// `graphql` is the application's GraphQL handler.
let app = App::new()
    .service(web::resource("/api/graphql").route(web::post().to(graphql)))
    .route("/graphiql", web::get().to(|| async { graphiql_html("/api/graphql") }));

Both helpers use the same pinned browser asset versions and escape the configured endpoint. UI registration does not change the runtime’s introspection setting. The Actix consumer example also serves the built-in UI on GET /graphiql, with GraphQL execution on /graphql. HTTP content negotiation applies to the GraphQL endpoint, not the HTML page.