docs/scripts/generate-api-index.mjs

/**
 * 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();