GraphQL elements

The elements of GraphQL schemas (SDL). Operations, the fields of the root operation types, are named by schema coordinate (Query.books), by kind and field (mutation.borrow) or by field (books); types and directives by name.

GraphQL text is read by the graphql WebAssembly module (graphql.web.mjs and graphql.web.wasm): give its URL with graphql-wasm-url on <apg-spec> or <apg-api-reference>, or to every element with configureGraphQLEngine(url). Type extensions are merged into their types, rules the schema breaks are listed as problems, and undefined types are shown unresolved. The documentation model ({"apigenieGraphQL": 1, …}) can be given instead and needs no module.

Operations are sent to graphql-endpoint, by default /graphql on the origin of the document. The proxy, the interceptors and the apg-request and apg-response events of Try it out apply.

<apg-spec spec-url="/schema.graphql" graphql-wasm-url="/wasm/graphql.web.mjs" graphql-endpoint="https://api.example.com/graphql">
	<apg-graphql-overview></apg-graphql-overview>
	<apg-graphql-operation name="Query.books"></apg-graphql-operation>
	<apg-graphql-type name="Book"></apg-graphql-type>
</apg-spec>

<apg-graphql-overview>

The description of a GraphQL schema, its file, root operation types, size and schema directives.

Loaded on its own with import "@mykulyak/apigenie-docs/components/apg-graphql-overview";.

Attributes

Attribute Property Type Default Description
heading-level headingLevel number 1 Level of the title heading (1–6).

And spec-url, spec, api and theme, like every element that shows a document: Where the document comes from.

CSS parts

Part Description
overview The container.
title The title: the heading the schema description starts with, or the file name (h1 unless heading-level says otherwise).
info The file line.
roots The root operation types.
type-link Links to the root types.
directive-link Links to the definitions of the schema’s directives.

Forwarded from the elements inside it:

<apg-graphql-operation>

A GraphQL operation, that is a field of a root operation type (Query.books): its arguments, the type it returns (with its fields), an example operation with variables and a response, code samples and Try it out.

Loaded on its own with import "@mykulyak/apigenie-docs/components/apg-graphql-operation";.

Attributes

Attribute Property Type Default Description
name name string The operation: its schema coordinate (Query.books), kind and field (mutation.borrow) or field (books).
heading-level headingLevel number 2 Level of the title heading.
endpoint endpoint string The endpoint the code samples post to; by default the one of Try it out.
hide-samples hideSamples boolean false Hide the code samples.
hide-try-it hideTryIt boolean false Hide Try it out.
lazy lazy boolean false Render only the header until the operation comes near the viewport (used for long pages; the full content is always rendered on the server).

And spec-url, spec, api and theme, like every element that shows a document: Where the document comes from.

Methods

Method Description
reveal() Renders the full content of a lazy operation.

CSS parts

Part Description
operation The container.
header The header with the name and badges.
title The name of the field.
coordinate The schema coordinate (Query.books).
summary The summary line, when the field has no description of its own.
badge Badges (deprecated).
section Sections (arguments, response, example, code samples, try it out).
section-title Section headings.
arguments The table of arguments.
argument An argument’s row.
type-link Links to type pages.
directive-link Links to directive definitions.

Forwarded from the elements inside it:

<apg-graphql-type>

A type of a GraphQL schema: object and interface types with their fields (and the fields’ arguments), input types with their fields and default values, enums with their values, unions with their members, and scalars; the interfaces a type implements, the types implementing an interface, the unions an object belongs to, where the type is used, and an example value of input types.

Loaded on its own with import "@mykulyak/apigenie-docs/components/apg-graphql-type";.

Attributes

Attribute Property Type Default Description
name name string The type, by name.
heading-level headingLevel number 2 Level of the title heading.
embedded embedded boolean false Shown inside an operation, whose heading names the type: its fields, values or members only.

And spec-url, spec, api and theme, like every element that shows a document: Where the document comes from.

CSS parts

Part Description
type The container.
header The header with the name and badges.
title The name.
kind The kind of the type (object, enum…).
badge Badges (root, deprecated).
section Sections (fields, values, members, used by…).
section-title Section headings.
fields The table of fields (or input fields).
field A field’s row.
arguments Tables of arguments.
argument An argument’s row.
values The table of enum values.
type-link Links to type pages.
operation-link Links to operation pages (fields of root types).
directive-link Links to directive definitions.

Forwarded from the elements inside it:

<apg-graphql-directive>

A directive definition of a GraphQL schema: its arguments, where it may be used and whether it is repeatable.

Loaded on its own with import "@mykulyak/apigenie-docs/components/apg-graphql-directive";.

Attributes

Attribute Property Type Default Description
name name string The directive, by name with or without @.
heading-level headingLevel number 2 Level of the title heading.

And spec-url, spec, api and theme, like every element that shows a document: Where the document comes from.

CSS parts

Part Description
directive The container.
header The header with the name and badges.
title The name (@name).
badge Badges (repeatable).
section Sections (arguments, locations).
section-title Section headings.
arguments The table of arguments.
argument An argument’s row.
type-link Links to type pages.
locations The list of locations.

Forwarded from the elements inside it:

<apg-graphql-code-samples>

Code samples sending a GraphQL operation with its example variables: curl, JavaScript (fetch) and Python (requests), each posting {query, variables, operationName} as JSON.

Loaded on its own with import "@mykulyak/apigenie-docs/components/apg-graphql-code-samples";.

Attributes

Attribute Property Type Default Description
operation operation string The operation: Query.books, query.books or books.
endpoint endpoint string The endpoint the samples post to; by default the one of Try it out.
languages languages string "curl,javascript,python" Comma-separated languages: curl, javascript, python.

And spec-url, spec, api and theme, like every element that shows a document: Where the document comes from.

CSS parts

Part Description
code-samples The container.
tab Language tabs; the selected one also has tab-active.
tab-active The selected tab.

Forwarded from the elements inside it:

<apg-graphql-try-it>

Sends a GraphQL operation to an endpoint: the operation (prefilled with the example), its variables and headers, posted as JSON. The endpoint and headers are shared by every operation of the schema. Subscriptions need a streaming transport and are not sent.

Events: apg-request (cancelable; detail.request may be replaced) before sending and apg-response afterwards.

Loaded on its own with import "@mykulyak/apigenie-docs/components/apg-graphql-try-it";.

Attributes

Attribute Property Type Default Description
operation operation string The operation: Query.books, query.books or books.

And spec-url, spec, api and theme, like every element that shows a document: Where the document comes from.

Events

Event Description
apg-request Before a request is sent; cancelable, detail.request may be replaced.
apg-response After a response (or failure).

CSS parts

Part Description
try-it The container.
section-title Headings of the form’s sections.
label Field labels.
input Text inputs.
textarea The operation and variables editors.
button Secondary buttons.
button-primary The Send button.
problems Problems that block the request.
response The response viewer.
response-status The response status code.
graphql-errors The errors of the response.
cors What a cross-origin request needs from the server, when it failed before a response.

Forwarded from the elements inside it:

Last updated on Edit this page on GitHubView as Markdown
Was this helpful?