feat: [docs] add v3 api refs alongwith updated MCP API refs (#1529)

Author: alt-glitch

.github/workflows/preview_docs.yml

@@ -50,8 +50,11 @@ jobs:
             - name: Install Fern
               run: npm install -g fern-api
 
+            - name: Install jq
+              run: sudo apt-get update && sudo apt-get install -y jq
+
             - name: Pull Latest OpenAPI Specification
-              run: sh scripts/pull-openapi-spec.sh
+              run: bash scripts/pull-openapi-spec.sh
 
             - name: Generate preview URL
               id: generate-docs

.github/workflows/publish_docs.yml

@@ -49,8 +49,11 @@ jobs:
       - name: Install Fern
         run: npm install -g fern-api
 
+      - name: Install jq
+        run: sudo apt-get update && sudo apt-get install -y jq
+
       - name: Pull Latest OpenAPI Specification
-        run: sh scripts/pull-openapi-spec.sh
+        run: bash scripts/pull-openapi-spec.sh
 
       - name: Publish Docs
         env:

.gitignore

@@ -1,75 +1,82 @@
+# Environment files
 .env
+
+# Jupyter notebooks
 try.ipynb
+refactor_debug.ipynb
+
+# Python cache and compiled files
+**/__pycache__
+*.pyc
 *pycache*
-user_data.json
+**/*.egg-info
+*egg-info*
+.mypy_cache/
+.ruff_cache
+.tox/
+
+# Virtual environments
 .venv
 venv*
+
+# Distribution and build directories
 **/dist
-.DS_Store
-*egg-info*
-**/composio_autogen.egg-info
-**/composio_llamaindex.egg-info
-**/__pycache__
-**/*.egg-info
-*.pyc
-.tox/
-.mypy_cache/
+build
+core/build/lib/*
+temp
+
+# Logs and caches
+**/coder_agent_logs_*
+**/.composio.coder.*
+.indexing_status.json
+.python/swe/logs
+python/swe/tests/logs_dir
+python/swe/dockerfiles/logs*
 
+# Coverage and test results
 .coverage
 coverage.xml
 junit.xml
+.pytest_cache
+.test_results
 
-core/build/lib/*
-
+# Node modules and other dependencies
 node_modules
+Pipfile.lock
+
+# System files
+.DS_Store
 ~
 
-Pipfile.lock
-build
-temp
+# Specific project directories and files
+**/composio_autogen.egg-info
+**/composio_llamaindex.egg-info
 .cache
-.pytest_cache
-.test_results
 .trunk
-refactor_debug.ipynb
-**/coder_agent_logs_*
-**/.composio.coder.*
-.indexing_status.json
-
-.ruff_cache
 
+# Dockerfiles and related directories
 python/dockerfiles/e2b-dev/composio
 python/dockerfiles/composio
 python/swe/dockerfiles/generated
-python/swe/dockerfiles/logs*
-python/swe/logs
-python/swe/tests/logs_dir
 python/swe/dockerfiles/indexed
 python/swe/agentic
 python/swe/dockerfiles/generated*
 
+# Fern SDK and tools
 fern/sdk/composio/
 fern/tools/*
 !fern/tools/introduction.mdx
 fern/code
+fern/api/openapi.json
+fern/api/openapi-v3.json
 
+# Cursor and GitHub styles
 .cursor/*
-
 .github/styles/*
-# !.github/styles/config/
-
 .github/styles/config/*
-# !.github/styles/config/vocabularies/
-
 .github/styles/config/vocabularies/*
-# !.github/styles/config/vocabularies/Base
-
 
+# Styles
 styles/*
-# !styles/config/
-
 styles/config/*
-# !styles/config/vocabularies/
-
 styles/config/vocabularies/*
-# !styles/config/vocabularies/Composio

fern/openapi-overrides.yml fern/api/openapi-overrides.ymlfern/openapi-overrides.yml renamed to fern/api/openapi-overrides.yml

@@ -0,0 +1,4 @@
+paths:
+  # Hide the MCP server validation endpoint
+  /api/v1/mcp/servers/validate/uuid:
+    x-hidden: true  # This will hide this endpoint completely

fern/api/openapi-v3-overrides.yml

@@ -1,5 +1,12 @@
-api: 
-  path: ./openapi.json
-  overrides: ./openapi-overrides.yml
-  settings: 
-    use-title: false
+api:
+  namespaces:
+    v1:
+      path: ./api/openapi.json
+      overrides: ./api/openapi-overrides.yml
+      settings: 
+        use-title: false
+    v3:
+      path: ./api/openapi-v3.json
+      overrides: ./api/openapi-v3-overrides.yml
+      settings: 
+        use-title: false

fern/generators.yml

@@ -5,24 +5,89 @@ set -e
 
 # Define the OpenAPI specification URL and paths
 OPENAPI_URL="https://backend.composio.dev/openapi.json"
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+OPENAPI_V3_URL="https://qa-apollo.composio.dev/api/v3/openapi.json"
+
+# Get the directory where the script is located, works in both CI and local environments
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}" 2>/dev/null || dirname "$0")" && pwd)"
 FERN_DIR="$(dirname "$SCRIPT_DIR")"
-OUTPUT_FILE="$FERN_DIR/openapi.json"
+API_DIR="$FERN_DIR/api"
+TEMP_FILE="/tmp/openapi-temp.json"
+TEMP_V3_FILE="/tmp/openapi-v3-temp.json"
+OUTPUT_FILE="$API_DIR/openapi.json"
+OUTPUT_V3_FILE="$API_DIR/openapi-v3.json"
+
+# Debug information
+echo "Script directory: $SCRIPT_DIR"
+echo "Fern directory: $FERN_DIR"
+echo "API directory: $API_DIR"
+
+# Create API directory if it doesn't exist
+mkdir -p "$API_DIR"
 
 echo "Pulling latest OpenAPI specification from $OPENAPI_URL"
 
 # Use curl to fetch the OpenAPI specification
-if curl -f -o "$OUTPUT_FILE" "$OPENAPI_URL"; then
-    echo "Successfully downloaded OpenAPI specification to $OUTPUT_FILE"
+if curl -f -o "$TEMP_FILE" "$OPENAPI_URL"; then
+    echo "Successfully downloaded OpenAPI specification to temporary file"
 else
     echo "Failed to download OpenAPI specification"
     exit 1
 fi
 
 # Validate that the file exists and is not empty
-if [ -s "$OUTPUT_FILE" ]; then
+if [ -s "$TEMP_FILE" ]; then
     echo "Verified OpenAPI specification file exists and is not empty"
 else
     echo "Error: OpenAPI specification file is empty or does not exist"
     exit 1
-fi 
+fi
+
+# Filter out specific paths using jq
+echo "Filtering out specified paths from OpenAPI specification"
+if command -v jq &> /dev/null; then
+    # Remove the path - try both formats since it could be either
+    jq 'del(.paths."/api/v1/mcp/servers/validate/uuid") | del(.paths."/api/v1/mcp/servers/validate/{uuid}")' "$TEMP_FILE" > "$OUTPUT_FILE"
+    echo "Successfully filtered OpenAPI specification and saved to $OUTPUT_FILE"
+else
+    echo "Warning: jq is not installed. Cannot filter paths."
+    echo "Please install jq with: brew install jq"
+    # Copy unfiltered file as fallback
+    cp "$TEMP_FILE" "$OUTPUT_FILE"
+fi
+
+# Fetch the OpenAPI v3 specification
+echo "Pulling latest OpenAPI v3 specification from $OPENAPI_V3_URL"
+if curl -f -o "$TEMP_V3_FILE" "$OPENAPI_V3_URL"; then
+    echo "Successfully downloaded OpenAPI v3 specification to temporary file"
+else
+    echo "Failed to download OpenAPI v3 specification"
+    exit 1
+fi
+
+# Validate that the v3 file exists and is not empty
+if [ -s "$TEMP_V3_FILE" ]; then
+    echo "Verified OpenAPI v3 specification file exists and is not empty"
+else
+    echo "Error: OpenAPI v3 specification file is empty or does not exist"
+    exit 1
+fi
+
+# Filter the v3 spec using jq
+if command -v jq &> /dev/null; then
+    # Remove the path - try both formats since it could be either
+    jq 'del(.paths."/api/v1/mcp/servers/validate/uuid") | del(.paths."/api/v1/mcp/servers/validate/{uuid}")' "$TEMP_V3_FILE" > "$OUTPUT_V3_FILE"
+    echo "Successfully filtered OpenAPI v3 specification and saved to $OUTPUT_V3_FILE"
+else
+    # Copy unfiltered file as fallback
+    cp "$TEMP_V3_FILE" "$OUTPUT_V3_FILE"
+fi
+
+# For debugging
+ls -la "$API_DIR"
+echo "FERN_DIR=$FERN_DIR"
+echo "API_DIR=$API_DIR"
+
+# Clean up temporary files
+rm "$TEMP_FILE" "$TEMP_V3_FILE"
+
+echo "OpenAPI specifications successfully updated"