Article API: deduplicate REST response schemas and simplify curl (#60073)

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

Author: heiskr

src/article-api/templates/rest-page.template.md

@@ -4,6 +4,9 @@
 
 {{ manualContent }}
 
+> [!NOTE]
+> Most endpoints use `Authorization: Bearer <YOUR-TOKEN>` and `Accept: application/vnd.github+json` headers{% if apiVersion %}, plus `X-GitHub-Api-Version: {{ apiVersion }}`{% endif %}. Curl examples below omit these standard headers for brevity.
+
 {% for operation in restOperations %}
 
 ## {{ operation.title }}
@@ -81,13 +84,8 @@
 ```curl
 curl -L \
   -X {{ operation.verb | upcase }} \
-  {{ example.request.url }} \
-{%- if example.request.acceptHeader %}
-  -H "Accept: {{ example.request.acceptHeader }}" \
-{%- endif %}
-  -H "Authorization: Bearer <YOUR-TOKEN>"{% if apiVersion %} \
-  -H "X-GitHub-Api-Version: {{ apiVersion }}"{% endif -%}
-{%- if example.request.bodyParameters %} \
+  {{ example.request.url }}{% if example.request.acceptHeader and example.request.acceptHeader != 'application/vnd.github+json' and example.request.acceptHeader != 'application/vnd.github.v3+json' %} \
+  -H "Accept: {{ example.request.acceptHeader }}"{% endif %}{% if example.request.bodyParameters %} \
   -d '{{ example.request.bodyParameters }}'{% endif %}
 ```
 

src/article-api/tests/rest-transformer.ts

@@ -113,25 +113,33 @@ describe('REST transformer', () => {
     expect(res.body).toContain('```curl')
     expect(res.body).toContain('curl -L \\')
     expect(res.body).toContain('-X GET \\')
-    expect(res.body).toContain('https://api.github.com/repos/OWNER/REPO/actions/artifacts \\')
-    expect(res.body).toContain('-H "Accept: application/vnd.github.v3+json" \\')
-    expect(res.body).toContain('-H "Authorization: Bearer <YOUR-TOKEN>"')
+    expect(res.body).toContain('https://api.github.com/repos/OWNER/REPO/actions/artifacts')
   })
 
-  test('Code examples include X-GitHub-Api-Version header by default', async () => {
+  test('Authentication note is included at top of page', async () => {
     const res = await get(makeURL('/en/rest/actions/artifacts'))
     expect(res.statusCode).toBe(200)
 
-    // Check for API version header in curl example
-    expect(res.body).toContain('-H "X-GitHub-Api-Version: 2026-03-10"')
+    // Check that auth note is at the top using [!NOTE] syntax
+    expect(res.body).toContain('[!NOTE]')
+    expect(res.body).toContain('Authorization: Bearer <YOUR-TOKEN>')
+    expect(res.body).toContain('application/vnd.github+json')
   })
 
-  test('Code examples include specified API version', async () => {
+  test('API version is mentioned in auth note', async () => {
+    const res = await get(makeURL('/en/rest/actions/artifacts'))
+    expect(res.statusCode).toBe(200)
+
+    // Check for API version in the auth note (any valid date format)
+    expect(res.body).toMatch(/X-GitHub-Api-Version: \d{4}-\d{2}-\d{2}/)
+  })
+
+  test('Code examples include specified API version in auth note', async () => {
     const res = await get(makeURL('/en/rest/actions/artifacts', '2022-11-28'))
     expect(res.statusCode).toBe(200)
 
-    // Check for the specified API version header
-    expect(res.body).toContain('-H "X-GitHub-Api-Version: 2022-11-28"')
+    // Check for the specified API version in auth note
+    expect(res.body).toContain('X-GitHub-Api-Version: 2022-11-28')
   })
 
   test('Liquid tags are rendered in intro', async () => {
@@ -224,16 +232,16 @@ describe('REST transformer', () => {
     const res = await get(makeURL('/en/rest/actions/artifacts', '2022-11-28'))
 
     expect(res.statusCode).toBe(200)
-    expect(res.body).toContain('-H "X-GitHub-Api-Version: 2022-11-28"')
+    expect(res.body).toContain('X-GitHub-Api-Version: 2022-11-28')
   })
 
   test('Missing apiVersion defaults to latest', async () => {
     // When no apiVersion is provided, it should default to the latest version
     const res = await get(makeURL('/en/rest/actions/artifacts'))
 
     expect(res.statusCode).toBe(200)
-    // Should include the default API version header
-    expect(res.body).toContain('-H "X-GitHub-Api-Version: 2026-03-10"')
+    // Should include the default API version in auth note (any valid date format)
+    expect(res.body).toMatch(/X-GitHub-Api-Version: \d{4}-\d{2}-\d{2}/)
   })
 
   test('Multiple operations on a page are all rendered', async () => {

src/article-api/transformers/rest-transformer.ts

@@ -6,6 +6,7 @@ import { loadTemplate } from '@/article-api/lib/load-template'
 import { summarizeSchema } from '@/article-api/lib/summarize-schema'
 import matter from '@gr2m/gray-matter'
 import { fastTextOnly } from '@/content-render/unified/text-only'
+import GithubSlugger from 'github-slugger'
 
 const DEBUG = process.env.RUNNER_DEBUG === '1' || process.env.DEBUG === '1'
 
@@ -134,6 +135,30 @@ export class RestTransformer implements PageTransformer {
       operations.map(async (operation) => await this.prepareOperation(operation)),
     )
 
+    // Deduplicate identical response schemas across operations on the same page.
+    // When multiple endpoints share the same schema, render it once and reference it.
+    const slugger = new GithubSlugger()
+    const titleToSlug = new Map<string, string>()
+    for (const op of preparedOperations) {
+      titleToSlug.set(op.title, slugger.slug(op.title))
+    }
+    const schemaMap = new Map<string, string>()
+    for (const op of preparedOperations) {
+      if (!op.codeExamples) continue
+      for (const example of op.codeExamples as any[]) {
+        const schema = example.response?.schema
+        if (!schema || typeof schema !== 'string') continue
+
+        const existing = schemaMap.get(schema)
+        if (existing && existing !== op.title) {
+          const slug = titleToSlug.get(existing) || ''
+          example.response.schema = `Same response schema as [${existing}](#${slug}).`
+        } else if (!existing) {
+          schemaMap.set(schema, op.title)
+        }
+      }
+    }
+
     return {
       page: {
         title: page.title,