Custom schema directives handling
Use customDirective to render a custom description or badge for the directives applied in your schema.
customDirective is deprecated in favor of decorators, which supersedes it. See migrating from customDirective.
You can select which directives are rendered for the types or locations where they are declared, with a custom description for each.
For example, a query called searchRole should be limited to ADMIN user roles. We can express this by adding a directive called auth with an argument requires to the query.
directive @auth(requires: Roles = ADMIN) on OBJECT | FIELD_DEFINITION
enum Roles {
ADMIN
USER
}
type Query {
searchRole(roles: [Roles!]! = [ADMIN]): Int! @auth
}
Usage
Add the option customDirective to the GraphQL-Markdown configuration.
The descriptor and tag functions receive 2 arguments:
directiveof typeGraphQLDirectivenodeof typeGraphQLNamedTypeorASTNode
type DirectiveName = string & { _opaque: typeof DirectiveName };
type CustomDirective = {
[name: DirectiveName]: {
descriptor?: (directive?: GraphQLDirective, node?: unknown): string;
tag?: (directive?: GraphQLDirective, node?: unknown): Badge;
};
};
type Badge = {
text: string | TypeLocale;
classname: string;
};
descriptor
The descriptor allows rendering the custom directive's description applicable to entities.
module.exports = {
schema: "./schema.graphql",
extensions: {
"graphql-markdown": {
// ... other options
customDirective: {
auth: {
descriptor: (directive, node) =>
directiveDescriptor(
directive,
node,
"This requires the current user to be in `${requires}` role.",
),
},
// ... other custom directive options
},
},
},
};
The descriptor output is printed as text: MDX special characters ({ } < > _ *) are escaped, so a descriptor cannot inject HTML, JSX or MDX into the page.
tag
The tag allows rendering custom badges (tags) based on the custom directive applicable to entities.
module.exports = {
schema: "./schema.graphql",
extensions: {
"graphql-markdown": {
// ... other options
customDirective: {
beta: {
tag: (directive, node) => ({
text: directive.name,
classname: "badge--info",
}),
},
// ... other custom directive options
},
},
},
};
Wildcard
You can use "*" as a wildcard for the directive name. This will allow all directives not declared with their name under customDirective to be handled by the wildcard descriptor and/or tag.
const {
directiveDescriptor,
directiveTag,
} = require("@graphql-markdown/helpers");
//...//
module.exports = {
schema: "./schema.graphql",
extensions: {
"graphql-markdown": {
// ... other options
customDirective: {
"*": {
descriptor: directiveDescriptor,
tag: directiveTag,
},
// ... optionally specific custom directive options
},
},
},
};
Helpers
The packages @graphql-markdown/helpers and @graphql-markdown/graphql provide a few helper functions to quickly start.
@graphql-markdown/helpers is an optional peer dependency, and it needs to be installed before using it.
- npm
- pnpm
- yarn
- bun
npm i @graphql-markdown/helpers
pnpm add @graphql-markdown/helpers
yarn add @graphql-markdown/helpers
bun add @graphql-markdown/helpers