Buckets:
AnonymousSpottedToad/candidate_bucket / codebase /python /li-boxuan_OpenDevin /scripts /update_openapi.py
| #!/usr/bin/env python3 | |
| """ | |
| Update OpenHands OpenAPI documentation. | |
| Generates the OpenAPI specification from the FastAPI application and writes it | |
| to docs/openapi.json. | |
| Usage: | |
| python scripts/update_openapi.py | |
| Behavior: | |
| - Uses openhands.server.app.app.openapi() to build the spec. | |
| - Preserves existing "servers" from docs/openapi.json if present; otherwise | |
| writes sensible defaults. | |
| - Sets info.version to openhands.__version__. | |
| - Sanitizes endpoint descriptions to remove code blocks and internal-only sections. | |
| - Excludes operational/UI-only convenience endpoints: | |
| - /server_info | |
| - /api/conversations/{conversation_id}/vscode-url | |
| - /api/conversations/{conversation_id}/web-hosts | |
| - Creates a backup docs/openapi.json.backup before overwriting. | |
| Output: | |
| - Prints OpenAPI and API versions, endpoint count, servers count, and sample endpoints. | |
| """ | |
| import json | |
| import logging | |
| import os | |
| import sys | |
| import warnings | |
| from pathlib import Path | |
| # Suppress warnings and logs during import | |
| logging.getLogger().setLevel(logging.CRITICAL) | |
| warnings.filterwarnings('ignore') | |
| os.environ['OPENHANDS_LOG_LEVEL'] = 'CRITICAL' | |
| # Add the project root to the Python path | |
| project_root = Path(__file__).parent.parent | |
| sys.path.insert(0, str(project_root)) | |
| try: | |
| from openhands import __version__ | |
| from openhands.server.app import app | |
| except ImportError as e: | |
| print(f'Error importing OpenHands modules: {e}') | |
| print( | |
| "Make sure you're running this script from the project root and dependencies are installed." | |
| ) | |
| sys.exit(1) | |
| def _sanitize_description(text: str) -> str: | |
| """Remove internal, code-centric, or redundant sections from endpoint descriptions. | |
| - Strip fenced code blocks | |
| - Remove Args/Returns/Raises/Example/Examples/Notes sections | |
| - Remove inline curl examples | |
| - Avoid provider-implementation specifics like LiteLLM/Bedrock | |
| """ | |
| import re | |
| if not text: | |
| return text | |
| # Remove fenced code blocks | |
| text = re.sub(r'```[\s\S]*?```', '', text, flags=re.MULTILINE) | |
| # Remove common docstring sections (until next blank line or end) | |
| for header in [ | |
| r'Args?:', | |
| r'Returns?:', | |
| r'Raises?:', | |
| r'Example[s]?:', | |
| r'Notes?:', | |
| ]: | |
| text = re.sub(rf'(?ms)^\s*{header}.*?(?:\n\s*\n|\Z)', '', text) | |
| # Remove lines that contain curl examples | |
| text = re.sub(r'(?im)^.*\bcurl\b.*$', '', text) | |
| # Generalize provider-implementation specifics | |
| text = re.sub(r'\bLiteLLM\b', 'configured model providers', text) | |
| text = re.sub(r'\blitellm\b', 'configured providers', text) | |
| text = re.sub(r'\bBedrock\b', '', text) | |
| # Collapse excessive blank lines and trim | |
| text = re.sub(r'\n{3,}', '\n\n', text).strip() | |
| return text | |
| def _sanitize_spec(spec: dict) -> dict: | |
| """Sanitize descriptions and summaries to be public-API friendly.""" | |
| path_summary_overrides = { | |
| '/api/options/models': 'List Supported Models', | |
| '/api/options/agents': 'List Agents', | |
| '/api/options/security-analyzers': 'List Security Analyzers', | |
| '/api/conversations/{conversation_id}/list-files': 'List Workspace Files', | |
| '/api/conversations/{conversation_id}/select-file': 'Get File Content', | |
| '/api/conversations/{conversation_id}/zip-directory': 'Download Workspace Archive', | |
| } | |
| path_description_overrides = { | |
| '/api/options/models': 'List model identifiers available on this server based on configured providers.', | |
| '/api/options/agents': 'List available agent types supported by this server.', | |
| '/api/options/security-analyzers': 'List supported security analyzers.', | |
| '/api/conversations/{conversation_id}/list-files': 'List workspace files visible to the conversation runtime. Applies .gitignore and internal ignore rules.', | |
| '/api/conversations/{conversation_id}/select-file': 'Return the content of the given file from the conversation workspace.', | |
| '/api/conversations/{conversation_id}/zip-directory': 'Return a ZIP archive of the current conversation workspace.', | |
| } | |
| for path, methods in list(spec.get('paths', {}).items()): | |
| for method, meta in list(methods.items()): | |
| if not isinstance(meta, dict): | |
| continue | |
| # Override overly specific summaries where helpful | |
| if path in path_summary_overrides: | |
| meta['summary'] = path_summary_overrides[path] | |
| # Override description if provided; otherwise sanitize | |
| if path in path_description_overrides: | |
| meta['description'] = path_description_overrides[path] | |
| elif 'description' in meta and isinstance(meta['description'], str): | |
| meta['description'] = _sanitize_description(meta['description']) | |
| return spec | |
| def generate_openapi_spec(): | |
| """Generate the OpenAPI specification from the FastAPI app.""" | |
| spec = app.openapi() | |
| # Explicitly exclude certain endpoints that are operational, experimental, or UI-only convenience | |
| excluded_endpoints = [ | |
| '/api/conversations/{conversation_id}/exp-config', # Internal experimentation endpoint | |
| '/server_info', # Operational/system diagnostics | |
| '/api/conversations/{conversation_id}/vscode-url', # UI/runtime convenience | |
| '/api/conversations/{conversation_id}/web-hosts', # UI/runtime convenience | |
| ] | |
| if 'paths' in spec: | |
| for endpoint in excluded_endpoints: | |
| if endpoint in spec['paths']: | |
| del spec['paths'][endpoint] | |
| print(f'Excluded endpoint: {endpoint}') | |
| # Sanitize descriptions and summaries | |
| spec = _sanitize_spec(spec) | |
| return spec | |
| def load_current_spec(spec_path): | |
| """Load the current OpenAPI specification if it exists.""" | |
| if spec_path.exists(): | |
| with open(spec_path, 'r') as f: | |
| return json.load(f) | |
| return {} | |
| def update_openapi_spec(spec_path, backup=True): | |
| """Update the OpenAPI specification file.""" | |
| # Generate new spec | |
| new_spec = generate_openapi_spec() | |
| # Load current spec for server information | |
| current_spec = load_current_spec(spec_path) | |
| # Preserve server information from current spec if it exists | |
| if 'servers' in current_spec: | |
| new_spec['servers'] = current_spec['servers'] | |
| else: | |
| # Default servers if none exist | |
| new_spec['servers'] = [ | |
| {'url': 'https://app.all-hands.dev', 'description': 'Production server'}, | |
| {'url': 'http://localhost:3000', 'description': 'Local server'}, | |
| ] | |
| # Update version to match the package version | |
| new_spec['info']['version'] = __version__ | |
| # Backup current file if requested | |
| if backup and spec_path.exists(): | |
| backup_path = spec_path.with_suffix('.json.backup') | |
| spec_path.rename(backup_path) | |
| print(f'Backed up current spec to {backup_path}') | |
| # Write new spec | |
| with open(spec_path, 'w') as f: | |
| json.dump(new_spec, f, indent=2) | |
| return new_spec | |
| def main(): | |
| """Main function.""" | |
| spec_path = project_root / 'docs' / 'openapi.json' | |
| print('Updating OpenAPI specification...') | |
| print(f'Target file: {spec_path}') | |
| try: | |
| new_spec = update_openapi_spec(spec_path) | |
| print('✅ Successfully updated OpenAPI specification!') | |
| print(f' OpenAPI version: {new_spec.get("openapi", "N/A")}') | |
| print(f' API version: {new_spec.get("info", {}).get("version", "N/A")}') | |
| print(f' Total endpoints: {len(new_spec.get("paths", {}))}') | |
| print(f' Servers: {len(new_spec.get("servers", []))}') | |
| # List some key endpoints | |
| paths = list(new_spec.get('paths', {}).keys()) | |
| if paths: | |
| print(' Sample endpoints:') | |
| for path in sorted(paths)[:5]: | |
| methods = list(new_spec['paths'][path].keys()) | |
| print(f' {path}: {methods}') | |
| if len(paths) > 5: | |
| print(f' ... and {len(paths) - 5} more') | |
| except Exception as e: | |
| print(f'❌ Error updating OpenAPI specification: {e}') | |
| sys.exit(1) | |
| if __name__ == '__main__': | |
| main() | |
Xet Storage Details
- Size:
- 8.17 kB
- Xet hash:
- 035f9c07118185ed2611b1684ff0debcc6cf7a55ea1e2ee11dff5fa80e9ffef7
·
Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.