docs/scripts/generate-api-index.mjs - superset - Git at Google

 /**
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
  * regarding copyright ownership.  The ASF licenses this file
  * to you under the Apache License, Version 2.0 (the
  * "License"); you may not use this file except in compliance
  * with the License.  You may obtain a copy of the License at
  *
  *   http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing,
  * software distributed under the License is distributed on an
  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  * KIND, either express or implied.  See the License for the
  * specific language governing permissions and limitations
  * under the License.
  */

 /**
  * Generates a comprehensive API index MDX file from the OpenAPI spec.
  * This creates the api.mdx landing page with all endpoints organized by category.
  *
  * Uses the generated sidebar to get correct endpoint slugs (the plugin's
  * slug algorithm differs from a simple slugify, e.g. handling apostrophes
  * and camelCase differently).
  */

 import fs from 'fs';
 import path from 'path';
 import { createRequire } from 'module';
 import { fileURLToPath } from 'url';

 const require = createRequire(import.meta.url);
 const __dirname = path.dirname(fileURLToPath(import.meta.url));

 const SPEC_PATH = path.join(__dirname, '..', 'static', 'resources', 'openapi.json');
 const SIDEBAR_PATH = path.join(__dirname, '..', 'developer_docs', 'api', 'sidebar.js');
 const OUTPUT_PATH = path.join(__dirname, '..', 'developer_docs', 'api.mdx');

 // Category groupings for better organization
 const CATEGORY_GROUPS = {
   'Authentication': ['Security'],
   'Core Resources': ['Dashboards', 'Charts', 'Datasets', 'Database'],
   'Data Exploration': ['Explore', 'SQL Lab', 'Queries', 'Datasources', 'Advanced Data Type'],
   'Organization & Customization': ['Tags', 'Annotation Layers', 'CSS Templates'],
   'Sharing & Embedding': [
     'Dashboard Permanent Link', 'Explore Permanent Link', 'SQL Lab Permanent Link',
     'Embedded Dashboard', 'Dashboard Filter State', 'Explore Form Data'
   ],
   'Scheduling & Alerts': ['Report Schedules'],
   'Security & Access Control': [
     'Security Roles', 'Security Users', 'Security Permissions',
     'Security Resources (View Menus)', 'Security Permissions on Resources (View Menus)',
     'Row Level Security'
   ],
   'Import/Export & Administration': ['Import/export', 'CacheRestApi', 'LogRestApi'],
   'User & System': ['Current User', 'User', 'Menu', 'Available Domains', 'AsyncEventsRestApi', 'OpenApi'],
 };

 /**
  * Build a map from sidebar label → doc slug by reading the generated sidebar.
  * This ensures we use the exact same slugs that docusaurus-openapi-docs generated.
  */
 function buildSlugMap() {
   const labelToSlug = {};

   try {
     const sidebar = require(SIDEBAR_PATH);

     const extractDocs = (items) => {
       for (const item of items) {
         if (item.type === 'doc' && item.label && item.id) {
           // id is like "api/create-security-login" → slug "create-security-login"
           const slug = item.id.replace(/^api\//, '');
           labelToSlug[item.label] = slug;
         }
         if (item.items) extractDocs(item.items);
       }
     };

     extractDocs(sidebar);
     console.log(`Loaded ${Object.keys(labelToSlug).length} slug mappings from sidebar`);
   } catch {
     console.warn('Could not read sidebar, will use computed slugs');
   }

   return labelToSlug;
 }

 function slugify(text) {
   return text
     .toLowerCase()
     .replace(/[^a-z0-9]+/g, '-')
     .replace(/(^-|-$)/g, '');
 }

 function main() {
   console.log(`Reading OpenAPI spec from ${SPEC_PATH}`);
   const spec = JSON.parse(fs.readFileSync(SPEC_PATH, 'utf-8'));

   // Build slug map from the generated sidebar
   const labelToSlug = buildSlugMap();

   // Build a map of tag -> endpoints
   const tagEndpoints = {};
   const tagDescriptions = {};

   // Get tag descriptions
   for (const tag of spec.tags || []) {
     tagDescriptions[tag.name] = tag.description || '';
   }

   // Collect endpoints by tag
   for (const [pathUrl, methods] of Object.entries(spec.paths || {})) {
     for (const [method, details] of Object.entries(methods)) {
       if (!['get', 'post', 'put', 'delete', 'patch'].includes(method)) continue;

       const tags = details.tags || ['Untagged'];
       const summary = details.summary || `${method.toUpperCase()} ${pathUrl}`;

       // Use sidebar slug if available, fall back to computed slug
       const slug = labelToSlug[summary] || slugify(summary);

       for (const tag of tags) {
         if (!tagEndpoints[tag]) {
           tagEndpoints[tag] = [];
         }
         tagEndpoints[tag].push({
           method: method.toUpperCase(),
           path: pathUrl,
           summary,
           slug,
         });
       }
     }
   }

   // Sort endpoints within each tag by path
   for (const tag of Object.keys(tagEndpoints)) {
     tagEndpoints[tag].sort((a, b) => a.path.localeCompare(b.path));
   }

   // Generate MDX content
   let mdx = `---
 title: API Reference
 hide_title: true
 sidebar_position: 10
 ---

 import { Alert } from 'antd';

 ## REST API Reference

 Superset exposes a comprehensive **REST API** that follows the [OpenAPI specification](https://swagger.io/specification/).
 You can use this API to programmatically interact with Superset for automation, integrations, and custom applications.

 <Alert
   type="info"
   showIcon
   message="Code Samples & Schema Documentation"
   description={
     <span>
       Each endpoint includes ready-to-use code samples in <strong>cURL</strong>, <strong>Python</strong>, and <strong>JavaScript</strong>.
       The sidebar includes <strong>Schema definitions</strong> for detailed data model documentation.
     </span>
   }
   style={{ marginBottom: '24px' }}
 />

 ---

 `;

   // Track which tags we've rendered
   const renderedTags = new Set();

   // Render Authentication first (it's critical for using the API)
   mdx += `### Authentication

 Most API endpoints require authentication via JWT tokens.

 #### Quick Start

 \`\`\`bash
 # 1. Get a JWT token
 curl -X POST http://localhost:8088/api/v1/security/login \\
   -H "Content-Type: application/json" \\
   -d '{"username": "admin", "password": "admin", "provider": "db"}'

 # 2. Use the access_token from the response
 curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \\
   http://localhost:8088/api/v1/dashboard/
 \`\`\`

 #### Security Endpoints

 `;

   // Render Security tag endpoints
   if (tagEndpoints['Security']) {
     mdx += `| Method | Endpoint | Description |\n`;
     mdx += `|--------|----------|-------------|\n`;
     for (const ep of tagEndpoints['Security']) {
       mdx += `| \`${ep.method}\` | [${ep.summary}](/developer-docs/api/${ep.slug}) | \`${ep.path}\` |\n`;
     }
     mdx += '\n';
     renderedTags.add('Security');
   }

   mdx += `---\n\n### API Endpoints\n\n`;

   // Render each category group
   for (const [groupName, groupTags] of Object.entries(CATEGORY_GROUPS)) {
     if (groupName === 'Authentication') continue; // Already rendered

     const tagsInGroup = groupTags.filter(tag => tagEndpoints[tag] && !renderedTags.has(tag));
     if (tagsInGroup.length === 0) continue;

     mdx += `#### ${groupName}\n\n`;

     for (const tag of tagsInGroup) {
       const description = tagDescriptions[tag] || '';
       const endpoints = tagEndpoints[tag];

       mdx += `<details>\n`;
       mdx += `<summary><strong>${tag}</strong> (${endpoints.length} endpoints) — ${description}</summary>\n\n`;
       mdx += `| Method | Endpoint | Description |\n`;
       mdx += `|--------|----------|-------------|\n`;

       for (const ep of endpoints) {
         mdx += `| \`${ep.method}\` | [${ep.summary}](/developer-docs/api/${ep.slug}) | \`${ep.path}\` |\n`;
       }

       mdx += `\n</details>\n\n`;
       renderedTags.add(tag);
     }
   }

   // Render any remaining tags not in a group
   const remainingTags = Object.keys(tagEndpoints).filter(tag => !renderedTags.has(tag));
   if (remainingTags.length > 0) {
     mdx += `#### Other\n\n`;

     for (const tag of remainingTags.sort()) {
       const description = tagDescriptions[tag] || '';
       const endpoints = tagEndpoints[tag];

       mdx += `<details>\n`;
       mdx += `<summary><strong>${tag}</strong> (${endpoints.length} endpoints) — ${description}</summary>\n\n`;
       mdx += `| Method | Endpoint | Description |\n`;
       mdx += `|--------|----------|-------------|\n`;

       for (const ep of endpoints) {
         mdx += `| \`${ep.method}\` | [${ep.summary}](/developer-docs/api/${ep.slug}) | \`${ep.path}\` |\n`;
       }

       mdx += `\n</details>\n\n`;
     }
   }

   mdx += `---

 ### Additional Resources

 - [Superset REST API Blog Post](https://preset.io/blog/2020-10-01-superset-api/)
 - [Accessing APIs with Superset](https://preset.io/blog/accessing-apis-with-superset/)
 `;

   // Write output
   fs.writeFileSync(OUTPUT_PATH, mdx);
   console.log(`Generated API index at ${OUTPUT_PATH}`);
   console.log(`Total tags: ${Object.keys(tagEndpoints).length}`);
   console.log(`Total endpoints: ${Object.values(tagEndpoints).flat().length}`);
 }

 main();
	/**
	* Licensed to the Apache Software Foundation (ASF) under one
	* or more contributor license agreements. See the NOTICE file
	* distributed with this work for additional information
	* regarding copyright ownership. The ASF licenses this file
	* to you under the Apache License, Version 2.0 (the
	* "License"); you may not use this file except in compliance
	* with the License. You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing,
	* software distributed under the License is distributed on an
	* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	* KIND, either express or implied. See the License for the
	* specific language governing permissions and limitations
	* under the License.
	*/

	/**
	* Generates a comprehensive API index MDX file from the OpenAPI spec.
	* This creates the api.mdx landing page with all endpoints organized by category.
	*
	* Uses the generated sidebar to get correct endpoint slugs (the plugin's
	* slug algorithm differs from a simple slugify, e.g. handling apostrophes
	* and camelCase differently).
	*/

	import fs from 'fs';
	import path from 'path';
	import { createRequire } from 'module';
	import { fileURLToPath } from 'url';

	const require = createRequire(import.meta.url);
	const __dirname = path.dirname(fileURLToPath(import.meta.url));

	const SPEC_PATH = path.join(__dirname, '..', 'static', 'resources', 'openapi.json');
	const SIDEBAR_PATH = path.join(__dirname, '..', 'developer_docs', 'api', 'sidebar.js');
	const OUTPUT_PATH = path.join(__dirname, '..', 'developer_docs', 'api.mdx');

	// Category groupings for better organization
	const CATEGORY_GROUPS = {
	'Authentication': ['Security'],
	'Core Resources': ['Dashboards', 'Charts', 'Datasets', 'Database'],
	'Data Exploration': ['Explore', 'SQL Lab', 'Queries', 'Datasources', 'Advanced Data Type'],
	'Organization & Customization': ['Tags', 'Annotation Layers', 'CSS Templates'],
	'Sharing & Embedding': [
	'Dashboard Permanent Link', 'Explore Permanent Link', 'SQL Lab Permanent Link',
	'Embedded Dashboard', 'Dashboard Filter State', 'Explore Form Data'
	],
	'Scheduling & Alerts': ['Report Schedules'],
	'Security & Access Control': [
	'Security Roles', 'Security Users', 'Security Permissions',
	'Security Resources (View Menus)', 'Security Permissions on Resources (View Menus)',
	'Row Level Security'
	],
	'Import/Export & Administration': ['Import/export', 'CacheRestApi', 'LogRestApi'],
	'User & System': ['Current User', 'User', 'Menu', 'Available Domains', 'AsyncEventsRestApi', 'OpenApi'],
	};

	/**
	* Build a map from sidebar label → doc slug by reading the generated sidebar.
	* This ensures we use the exact same slugs that docusaurus-openapi-docs generated.
	*/
	function buildSlugMap() {
	const labelToSlug = {};

	try {
	const sidebar = require(SIDEBAR_PATH);

	const extractDocs = (items) => {
	for (const item of items) {
	if (item.type === 'doc' && item.label && item.id) {
	// id is like "api/create-security-login" → slug "create-security-login"
	const slug = item.id.replace(/^api\//, '');
	labelToSlug[item.label] = slug;
	}
	if (item.items) extractDocs(item.items);
	}
	};

	extractDocs(sidebar);
	console.log(`Loaded ${Object.keys(labelToSlug).length} slug mappings from sidebar`);
	} catch {
	console.warn('Could not read sidebar, will use computed slugs');
	}

	return labelToSlug;
	}

	function slugify(text) {
	return text
	.toLowerCase()
	.replace(/[^a-z0-9]+/g, '-')
	.replace(/(^-\|-$)/g, '');
	}

	function main() {
	console.log(`Reading OpenAPI spec from ${SPEC_PATH}`);
	const spec = JSON.parse(fs.readFileSync(SPEC_PATH, 'utf-8'));

	// Build slug map from the generated sidebar
	const labelToSlug = buildSlugMap();

	// Build a map of tag -> endpoints
	const tagEndpoints = {};
	const tagDescriptions = {};

	// Get tag descriptions
	for (const tag of spec.tags \|\| []) {
	tagDescriptions[tag.name] = tag.description \|\| '';
	}

	// Collect endpoints by tag
	for (const [pathUrl, methods] of Object.entries(spec.paths \|\| {})) {
	for (const [method, details] of Object.entries(methods)) {
	if (!['get', 'post', 'put', 'delete', 'patch'].includes(method)) continue;

	const tags = details.tags \|\| ['Untagged'];
	const summary = details.summary \|\| `${method.toUpperCase()} ${pathUrl}`;

	// Use sidebar slug if available, fall back to computed slug
	const slug = labelToSlug[summary] \|\| slugify(summary);

	for (const tag of tags) {
	if (!tagEndpoints[tag]) {
	tagEndpoints[tag] = [];
	}
	tagEndpoints[tag].push({
	method: method.toUpperCase(),
	path: pathUrl,
	summary,
	slug,
	});
	}
	}
	}

	// Sort endpoints within each tag by path
	for (const tag of Object.keys(tagEndpoints)) {
	tagEndpoints[tag].sort((a, b) => a.path.localeCompare(b.path));
	}

	// Generate MDX content
	let mdx = `---
	title: API Reference
	hide_title: true
	sidebar_position: 10
	---

	import { Alert } from 'antd';

	## REST API Reference

	Superset exposes a comprehensive REST API that follows the [OpenAPI specification](https://swagger.io/specification/).
	You can use this API to programmatically interact with Superset for automation, integrations, and custom applications.

	<Alert
	type="info"
	showIcon
	message="Code Samples & Schema Documentation"
	description={
	<span>
	Each endpoint includes ready-to-use code samples in <strong>cURL</strong>, <strong>Python</strong>, and <strong>JavaScript</strong>.
	The sidebar includes <strong>Schema definitions</strong> for detailed data model documentation.
	</span>
	}
	style={{ marginBottom: '24px' }}
	/>

	---

	`;

	// Track which tags we've rendered
	const renderedTags = new Set();

	// Render Authentication first (it's critical for using the API)
	mdx += `### Authentication

	Most API endpoints require authentication via JWT tokens.

	#### Quick Start

	\`\`\`bash
	# 1. Get a JWT token
	curl -X POST http://localhost:8088/api/v1/security/login \\
	-H "Content-Type: application/json" \\
	-d '{"username": "admin", "password": "admin", "provider": "db"}'

	# 2. Use the access_token from the response
	curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \\
	http://localhost:8088/api/v1/dashboard/
	\`\`\`

	#### Security Endpoints

	`;

	// Render Security tag endpoints
	if (tagEndpoints['Security']) {
	mdx += `\| Method \| Endpoint \| Description \|\n`;
	mdx += `\|--------\|----------\|-------------\|\n`;
	for (const ep of tagEndpoints['Security']) {
	mdx += `\| \`${ep.method}\` \| [${ep.summary}](/developer-docs/api/${ep.slug}) \| \`${ep.path}\` \|\n`;
	}
	mdx += '\n';
	renderedTags.add('Security');
	}

	mdx += `---\n\n### API Endpoints\n\n`;

	// Render each category group
	for (const [groupName, groupTags] of Object.entries(CATEGORY_GROUPS)) {
	if (groupName === 'Authentication') continue; // Already rendered

	const tagsInGroup = groupTags.filter(tag => tagEndpoints[tag] && !renderedTags.has(tag));
	if (tagsInGroup.length === 0) continue;

	mdx += `#### ${groupName}\n\n`;

	for (const tag of tagsInGroup) {
	const description = tagDescriptions[tag] \|\| '';
	const endpoints = tagEndpoints[tag];

	mdx += `<details>\n`;
	mdx += `<summary><strong>${tag}</strong> (${endpoints.length} endpoints) — ${description}</summary>\n\n`;
	mdx += `\| Method \| Endpoint \| Description \|\n`;
	mdx += `\|--------\|----------\|-------------\|\n`;

	for (const ep of endpoints) {
	mdx += `\| \`${ep.method}\` \| [${ep.summary}](/developer-docs/api/${ep.slug}) \| \`${ep.path}\` \|\n`;
	}

	mdx += `\n</details>\n\n`;
	renderedTags.add(tag);
	}
	}

	// Render any remaining tags not in a group
	const remainingTags = Object.keys(tagEndpoints).filter(tag => !renderedTags.has(tag));
	if (remainingTags.length > 0) {
	mdx += `#### Other\n\n`;

	for (const tag of remainingTags.sort()) {
	const description = tagDescriptions[tag] \|\| '';
	const endpoints = tagEndpoints[tag];

	mdx += `<details>\n`;
	mdx += `<summary><strong>${tag}</strong> (${endpoints.length} endpoints) — ${description}</summary>\n\n`;
	mdx += `\| Method \| Endpoint \| Description \|\n`;
	mdx += `\|--------\|----------\|-------------\|\n`;

	for (const ep of endpoints) {
	mdx += `\| \`${ep.method}\` \| [${ep.summary}](/developer-docs/api/${ep.slug}) \| \`${ep.path}\` \|\n`;
	}

	mdx += `\n</details>\n\n`;
	}
	}

	mdx += `---

	### Additional Resources

	- [Superset REST API Blog Post](https://preset.io/blog/2020-10-01-superset-api/)
	- [Accessing APIs with Superset](https://preset.io/blog/accessing-apis-with-superset/)
	`;

	// Write output
	fs.writeFileSync(OUTPUT_PATH, mdx);
	console.log(`Generated API index at ${OUTPUT_PATH}`);
	console.log(`Total tags: ${Object.keys(tagEndpoints).length}`);
	console.log(`Total endpoints: ${Object.values(tagEndpoints).flat().length}`);
	}

	main();