bito-code-review[bot] commented on code in PR #37434: URL: https://github.com/apache/superset/pull/37434#discussion_r2733489966
########## docs/scripts/generate-api-index.mjs: ########## @@ -0,0 +1,240 @@ +/** + * 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. + */ + +import fs from 'fs'; +import path from 'path'; +import { fileURLToPath } from 'url'; + +const __filename = fileURLToPath(import.meta.url); +const __dirname = path.dirname(__filename); + +const SPEC_PATH = path.join(__dirname, '..', 'static', 'resources', 'openapi.json'); +const OUTPUT_PATH = path.join(__dirname, '..', 'docs', 'api.mdx'); Review Comment: <!-- Bito Reply --> The suggestion to remove 'docs' from the OUTPUT_PATH is incorrect. The script in docs/scripts/ uses __dirname as docs/scripts/, so path.join(__dirname, '..', 'docs', 'api.mdx') correctly points to docs/docs/api.mdx, matching the file updated in the PR. Without 'docs', it would target docs/api.mdx, which doesn't align with the actual output location. ########## docs/scripts/generate-api-index.mjs: ########## @@ -0,0 +1,240 @@ +/** + * 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. + */ + +import fs from 'fs'; +import path from 'path'; +import { fileURLToPath } from 'url'; + +const __filename = fileURLToPath(import.meta.url); +const __dirname = path.dirname(__filename); + +const SPEC_PATH = path.join(__dirname, '..', 'static', 'resources', 'openapi.json'); +const OUTPUT_PATH = path.join(__dirname, '..', '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'], +}; + +function slugify(text) { + return text + .toLowerCase() + .replace(/[^a-z0-9]+/g, '-') + .replace(/(^-|-$)/g, ''); +} + +function generateEndpointLink(summary) { + // Convert summary to the slug format used by docusaurus-openapi-docs + return slugify(summary); +} + +function main() { Review Comment: <!-- Bito Reply --> Your reasoning makes sense for a build script. Letting Node throw the native error provides a clear stack trace directly pointing to the issue (missing file or invalid JSON), which is more helpful for debugging than a wrapped error. For build-time failures, explicit errors are preferable to silent failures or generic messages. **docs/scripts/generate-api-index.mjs** ``` const spec = JSON.parse(fs.readFileSync(SPEC_PATH, 'utf-8')); ``` -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
