Introspection and GraphiQL

GraphQL schema introspection is enabled by default in necrassrs::execute. It returns metadata from the validated Apollo 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, post}};
use necrassrs_axum::{graphiql_html, negotiate_response};

let app = Router::new().route("/graphql",
    post(graphql).route_layer(middleware::from_fn(negotiate_response)));
let app = if development {
    app.route("/graphql", 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 /graphql by default. The page sends requests to POST /graphql. Remove or gate the GET 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 serves the built-in UI on GET /graphql by default, with execution on POST /graphql. HTTP content negotiation applies to the GraphQL endpoint, not the HTML page; see HTTP adapters and response negotiation.