Add GraphQL transformer for Article API (#58719)

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: heiskr

src/article-api/README.md

@@ -23,7 +23,12 @@ The `/api/article` endpoints return information about a page by `pathname`.
 
 ### Autogenerated Content Transformers
 
-For autogenerated pages (REST, landing pages, audit logs, webhooks, GraphQL, etc), the Article API uses specialized transformers to convert the rendered content into markdown format. These transformers are located in `src/article-api/transformers/` and use an extensible architecture:
+For autogenerated pages (REST, GraphQL, webhooks, landing pages, audit logs, etc), the Article API uses specialized transformers to convert the rendered content into markdown format. These transformers are located in `src/article-api/transformers/` and use an extensible architecture:
+
+#### Current Transformers
+
+- **REST Transformer** (`rest-transformer.ts`) - Converts REST API operations into markdown, including endpoints, parameters, status codes, and code examples
+- **GraphQL Transformer** (`graphql-transformer.ts`) - Converts GraphQL schema documentation into markdown, including queries, mutations, objects, interfaces, enums, unions, input objects, scalars, changelog, and breaking changes
 
 To add a new transformer for other autogenerated content types:
 1. Create a new transformer file implementing the `PageTransformer` interface

src/article-api/templates/graphql-breaking-changes.template.md

@@ -0,0 +1,21 @@
+# {{ pageTitle }}
+
+{{ pageIntro }}
+
+{{ manualContent }}
+
+{% for change in breakingChangesByDate %}
+
+## {{ change.heading }}
+
+{% for item in change.items %}
+
+- {% if item.criticality == 'breaking' %}**Breaking**{% else %}**Dangerous**{% endif %} A change will be made to `{{ item.location }}`.
+
+  **Description:** {{ item.description }}
+
+  **Reason:** {{ item.reason }}
+
+{% endfor %}
+
+{% endfor %}

src/article-api/templates/graphql-changelog.template.md

@@ -0,0 +1,38 @@
+# {{ pageTitle }}
+
+{{ pageIntro }}
+
+{{ manualContent }}
+
+{% for item in changelogItems %}
+
+## Schema changes for {{ item.date }}
+
+{% for schemaChange in item.schemaChanges %}
+
+### {{ schemaChange.title }}
+
+{% for change in schemaChange.changes %}- {{ change }}
+{% endfor %}
+
+{% endfor %}
+
+{% for previewChange in item.previewChanges %}
+
+### {{ previewChange.title }}
+
+{% for change in previewChange.changes %}- {{ change }}
+{% endfor %}
+
+{% endfor %}
+
+{% for upcomingChange in item.upcomingChanges %}
+
+### {{ upcomingChange.title }}
+
+{% for change in upcomingChange.changes %}- {{ change }}
+{% endfor %}
+
+{% endfor %}
+
+{% endfor %}

src/article-api/templates/graphql-index.template.md

@@ -0,0 +1,9 @@
+# {{ pageTitle }}
+
+{{ pageIntro }}
+
+{{ manualContent }}
+
+## Reference pages
+
+{{ childrenLinks }}

src/article-api/templates/graphql-reference.template.md

@@ -0,0 +1,120 @@
+# {{ pageTitle }}
+
+{{ pageIntro }}
+
+{{ manualContent }}
+
+{% for item in items %}
+
+## {{ item.name }}
+
+{{ item.description }}
+
+{% if item.isDeprecated %}
+
+> [!WARNING]
+> **Deprecation notice:** {{ item.deprecationReason }}
+{% endif %}
+
+{% if pageType == 'queries' %}
+**Type:** [{{ item.type }}]({{ item.href }})
+
+{% if item.args.size > 0 %}
+
+### Arguments for `{{ item.name }}`
+
+| Name | Type | Description |
+| --- | --- | --- |
+{% for arg in item.args %}| `{{ arg.name }}` | [`{{ arg.type }}`]({{ arg.href }}) | {{ arg.description }} |
+{% endfor %}
+{% endif %}
+
+{% elsif pageType == 'mutations' %}
+{% if item.inputFields.size > 0 %}
+
+### Input fields for `{{ item.name }}`
+
+| Name | Type | Description |
+| --- | --- | --- |
+{% for field in item.inputFields %}| `{{ field.name }}` | [`{{ field.type }}`]({{ field.href }}) | {{ field.description }}{% if field.defaultValue %} Default: `{{ field.defaultValue }}`.{% endif %} |
+{% endfor %}
+{% endif %}
+
+{% if item.returnFields.size > 0 %}
+
+### Return fields for `{{ item.name }}`
+
+| Name | Type | Description |
+| --- | --- | --- |
+{% for field in item.returnFields %}| `{{ field.name }}` | [`{{ field.type }}`]({{ field.href }}) | {{ field.description }}{% if field.defaultValue %} Default: `{{ field.defaultValue }}`.{% endif %}{% if field.isDeprecated %} **Deprecated:** {{ field.deprecationReason }}{% endif %} |
+{% endfor %}
+{% endif %}
+
+{% elsif pageType == 'objects' %}
+{% if item.implements.size > 0 %}
+
+### Implements
+
+{% for impl in item.implements %}- [`{{ impl.name }}`]({{ impl.href }})
+{% endfor %}
+{% endif %}
+
+{% if item.fields.size > 0 %}
+
+### Fields for `{{ item.name }}`
+
+| Name | Type | Description |
+| --- | --- | --- |
+{% for field in item.fields %}| `{{ field.name }}` | [`{{ field.type }}`]({{ field.href }}) | {{ field.description }}{% if field.defaultValue %} Default: `{{ field.defaultValue }}`.{% endif %}{% if field.isDeprecated %} **Deprecated:** {{ field.deprecationReason }}{% endif %}{% if field.arguments.size > 0 %}<br><br>**Arguments:**<br>{% for arg in field.arguments %}- `{{ arg.name }}` ([`{{ arg.type.name }}`]({{ arg.type.href }})): {{ arg.description }}{% if arg.defaultValue %} Default: `{{ arg.defaultValue }}`.{% endif %}<br>{% endfor %}{% endif %} |
+{% endfor %}
+{% endif %}
+
+{% elsif pageType == 'interfaces' %}
+{% if item.fields.size > 0 %}
+
+### Fields for `{{ item.name }}`
+
+| Name | Type | Description |
+| --- | --- | --- |
+{% for field in item.fields %}| `{{ field.name }}` | [`{{ field.type }}`]({{ field.href }}) | {{ field.description }}{% if field.defaultValue %} Default: `{{ field.defaultValue }}`.{% endif %}{% if field.isDeprecated %} **Deprecated:** {{ field.deprecationReason }}{% endif %}{% if field.arguments.size > 0 %}<br><br>**Arguments:**<br>{% for arg in field.arguments %}- `{{ arg.name }}` ([`{{ arg.type.name }}`]({{ arg.type.href }})): {{ arg.description }}{% if arg.defaultValue %} Default: `{{ arg.defaultValue }}`.{% endif %}<br>{% endfor %}{% endif %} |
+{% endfor %}
+{% endif %}
+
+{% elsif pageType == 'enums' %}
+{% if item.values.size > 0 %}
+
+### Values for `{{ item.name }}`
+
+{% for value in item.values %}**`{{ value.name }}`**
+
+{{ value.description }}
+
+{% endfor %}
+{% endif %}
+
+{% elsif pageType == 'unions' %}
+{% if item.possibleTypes.size > 0 %}
+
+### Possible types for `{{ item.name }}`
+
+{% for type in item.possibleTypes %}- [`{{ type.name }}`]({{ type.href }})
+{% endfor %}
+{% endif %}
+
+{% elsif pageType == 'inputObjects' %}
+{% if item.inputFields.size > 0 %}
+
+### Input fields for `{{ item.name }}`
+
+| Name | Type | Description |
+| --- | --- | --- |
+{% for field in item.inputFields %}| `{{ field.name }}` | [`{{ field.type }}`]({{ field.href }}) | {{ field.description }}{% if field.defaultValue %} Default: `{{ field.defaultValue }}`.{% endif %}{% if field.isDeprecated %} **Deprecated:** {{ field.deprecationReason }}{% endif %} |
+{% endfor %}
+{% endif %}
+
+{% elsif pageType == 'scalars' %}
+{%- comment -%}Scalars typically just have name and description{%- endcomment -%}
+
+{% endif %}
+
+{% endfor %}