diff --git a/doc/user_guide/dashbot_user_guide.md b/doc/user_guide/dashbot_user_guide.md new file mode 100644 index 00000000..6eba946b --- /dev/null +++ b/doc/user_guide/dashbot_user_guide.md @@ -0,0 +1,271 @@ +# Dashbot User Guide + +Dashbot is your in-app helper for working with APIs inside API Dash. It explains responses, helps fix failing requests, imports cURL/OpenAPI, generates documentation, tests, and runnable code — all without leaving your current request. + + +## Before You Start +- **Configure an AI model** : Open the AI Request settings and set your preferred provider/model and API key. Dashbot needs this to generate answers. If not configured, you will see a message asking you to set it up. +- **Pick or create a request** : Dashbot works best when a request is selected, especially for Explain, Debug, Tests, Docs, and Code. +- **Network access** : Some features pull insights only from your current request and input. No external API calls are made by Dashbot itself (outside your configured AI provider). + +## Open Dashbot +- Floating window: Click the Dashbot button to open it as a floating panel. + - Move: Drag the colored top bar to reposition. + - Resize: Drag the small handle at the top-left corner. + - Pop in/out: Use the “open in new” icon to toggle between the floating window and the in-tab view. + - Close: Click the Close icon. You can reopen anytime. +- In a tab: Use the Dashbot tab for a docked experience with back and close controls. + +![Image](./images/dashbot/dashbot_fab.png) +![Image](./images/dashbot/dashbot_pop_up.png) +![Image](./images/dashbot/dashbot_tab_view.png) + +## Home Screen Tasks +Dashbot’s home screen lists quick actions: +- Explain response: Explains the last response for the selected request. +- Debug error: Analyzes a failing response and proposes minimal fixes. +- Generate documentation: Creates clean Markdown docs for your request/response and lets you download them. +- Generate tests: Builds simple JavaScript tests; you can add them to the request’s post-request script. +- Generate code: Produces runnable code in common languages. +- Import cURL: Paste a full cURL to recreate a request. +- Import OpenAPI: Upload, paste, or fetch (URL) a spec and import endpoints. + +![Image](./images/dashbot/dashbot_tasks.png) + +--- + +## Import cURL +Turn a cURL command into an API Dash request without manual setup. + +How it works +1) Choose “Import cURL”. +2) Paste a complete command starting with `curl ...`. +3) Dashbot parses the command and shows: + - A short summary (method, URL, headers, body type) + - A diff preview vs your currently selected request (if any) + - Action buttons: + - Apply to Selected: Update the currently selected request. + - Create New Request: Add a new request to your collection. +4) Click an action to apply. + +Base URL as environment +- Dashbot detects the base URL and may rewrite your request URL as `{{BASE_URL_}}/path`. +- It will create or update a variable in your active Environment (for example `BASE_URL_API_EXAMPLE_COM`). +- See Environment guide for details on editing values. + +What’s included from cURL +- Method, full URL +- Headers (including Cookie, User-Agent, Referer; Basic auth from `-u user:pass`) +- Body or form data when present + +Known limits +- Some flags do not map to requests (e.g., `-k` insecure SSL, `-L` follow redirects, or very advanced curl options). Review and adjust after import if needed. +- If parsing fails, ensure the command is complete and starts with `curl`. + +![Image](./images/dashbot/dashbot_curl_paste.png) +![Image](./images/dashbot/dashbot_curl_result.png) + + +--- + +## Import OpenAPI +Import endpoints from an OpenAPI (Swagger) spec to quickly scaffold requests. + +Supported input +- JSON or YAML OpenAPI files. +- Public URL to a JSON or YAML OpenAPI document (e.g., `https://api.apidash.dev/openapi.json`). +- Upload via the “Upload Attachment” button (file picker), paste the full spec into the chat box, or enter a URL in the chat field and fetch. + +Workflow +1) Choose “Import OpenAPI”. +2) Provide the spec by uploading, pasting, or entering a URL then clicking Fetch. +3) If valid, Dashbot shows a summary plus an “Import Now” button. +4) Click “Import Now” to open the Operation Picker. +5) In the picker: + - Select All or cherry-pick operations (multi-select). + - Click Import to add them as new requests. +6) New requests are named like `GET /users`, `POST /items`, etc. + +Base URL as environment +- If the spec defines servers, Dashbot will infer the base URL and may rewrite imported URLs to use an environment variable like `{{BASE_URL_}}`. + +URL fetching notes +- The URL must be publicly reachable and return raw JSON or YAML (not an HTML page). +- Auth-protected or dynamically generated docs pages may fail; download and upload the spec instead. +- Large remote specs may take longer; try file upload if a timeout occurs. + +Notes and limits +- Very large specs may take longer and could show only the first N routes for performance. +- Some request body examples or schema-derived form fields may not auto-populate if missing explicit examples. +- “Apply to Selected” is supported when importing a single operation via certain actions, but the Operation Picker’s “Import” creates new requests. +- If URL import fails, verify the URL returns the spec directly and that no authentication is required. + +![Image](./images/dashbot/dashbot_openapi_task.png) +![Image](./images/dashbot/dashbot_openapi_file_picker.png) +![Image](./images/dashbot/dashbot_openapi_response.png) +![Image](./images/dashbot/dashbot_openapi_route_selection.png) + +--- + +## Explain Response +Get a clear, friendly explanation for the selected request. + +Use when +- You received a status like 2xx/4xx/5xx and want a quick understanding. + +What you get +- Short summary of what happened +- Explanation of the status code in simple terms +- Key details from the response body +- Likely causes or conditions +- Practical next steps + +Tips +- The explanation is textual. There are no “Auto Fix” actions in this mode. +- Use the copy icon to copy the response for documentation or sharing. + +![Image](./images/dashbot/dashbot_explanation.png) + +--- + +## Debug Error (Auto Fix) +Diagnose a failing request and apply suggested fixes with one click. + +Use when +- Your request returns 4xx/5xx or unexpected results. + +What you get +- Human-friendly analysis of the problem +- A plan of suggested changes (method/URL/headers/params/body) +- Action buttons (Auto Fix) that apply the change directly + +Applying fixes +- Click “Auto Fix” on a suggested change: + - Update field: URL, method, parameters + - Headers: add/update/delete + - Body: replace or set content type + - Apply cURL/OpenAPI: import payloads to selected or new request +- Changes apply to the currently selected request. + +Undo and safety +- Review changes before running again. If you need to revert, use your request history or edit fields manually. +- Dashbot aims for minimal, targeted changes. You control what to apply. + +![Image](./images/dashbot/dashbot_debug_error.png) +![Image](./images/dashbot/dashbot_debug_result.png) + +--- + +## Generate Documentation +Produce clean Markdown docs for your request/response. + +How to use +1) Choose “Generate documentation”. +2) Dashbot returns Markdown with: + - Title and description + - Request details (method, URL, headers, parameters) + - Response details and codes + - Example responses + - Key takeaways +3) Use an action: + - Copy: Copies the Markdown to your clipboard. + - Download Now: Saves a `.md` file to your system Downloads folder (auto-generated filename like `api-documentation.md`). + +Notes +- Downloaded file is plain Markdown; move or rename it as needed. +- If a file name collision occurs, a numeric suffix may be appended. + +![Image](./images/dashbot/dashbot_documentation.png) + +--- + +## Generate Tests +Create lightweight JavaScript tests for your request. + +How it works +1) Choose “Generate Tests”. +2) Dashbot replies with a test plan and a code action. +3) Click “Add Test” to insert the code into the request’s post-request script. +4) Send the request to execute the script after the response. + +Where tests go +- Tests are added to the current request’s post-request script area. +- You can modify or remove the script anytime. + +Notes and limits +- Tests are self-contained (no external packages). They run with plain JavaScript features. +- Add real credentials or tokens if needed; placeholders are used when values are unknown. + +![Image](./images/dashbot/dashbot_tests.png) +![Image](./images/dashbot/dashbot_tests_res.png) + +--- + +## Generate Code +Get runnable code samples for the current request in popular languages. + +Workflow +1) Choose “Generate Code”. +2) Select a language from the buttons (JavaScript, Python, Dart, Go, cURL). +3) Dashbot returns a code block. Copy it and run in your environment. + +What you get +- Minimal script that sends your request +- Respect for method/URL/headers/params/body +- Basic error handling and printing of status/body +- Notes about any required libraries (with install commands) when applicable + +Tips +- Replace placeholders (API keys/tokens) with real values. +- Verify content types and body structures match your API. + +![Image](./images/dashbot/dashbot_codegen.png) +![Image](./images/dashbot/dashbot_codegen_res_1.png) +![Image](./images/dashbot/dashbot_codegen_res_2.png) + +--- + +## Action Buttons Explained +- Apply to Selected: Applies changes to the currently selected request. +- Create New Request: Adds a new request with the suggested setup. +- Import Now (OpenAPI): Opens an operation picker to import endpoints. +- Auto Fix: Applies a specific change (header/url/method/body/params) to the selected request. +- Select Operation: Appears for certain OpenAPI actions to apply a single operation. +- Language buttons: Ask Dashbot to generate code in a specific language. +- Add Test: Appends test code to your post-request script. + +--- + +## Environment Integration +- Base URL variables: Dashbot can auto-create `{{BASE_URL_}}` variables in your active environment when importing cURL/OpenAPI. +- Editing values: Open the Environment manager to update base URLs per environment. See the [Environment Variables](./env_user_guide.md) guide. + +![Image](./images/dashbot/dashbot_env_vars.png) + +--- + +## Capabilities and Limitations +- Focus: Dashbot is focused on API tasks. It will refuse unrelated questions. +- Minimal changes: Auto Fix aims for small, safe edits you approve explicitly. +- Placeholders: When values are unknown, placeholders like `YOUR_API_KEY` are used — replace them. +- cURL flags: Not all flags map 1:1 (e.g., `-k`, `-L`). Review results. +- OpenAPI edge cases: Some specs may omit examples or complex schemas; imports may need manual tweaks. +- Code/tests: Generated snippets are examples. Validate and adapt before production use. + +--- + +## Troubleshooting +- AI model is not configured: Set it in the AI Request settings; then retry. +- cURL parsing failed: Ensure the command starts with `curl` and is complete. Remove shell-specific parts and try again. +- OpenAPI parsing failed (file/paste): Make sure the spec is valid JSON/YAML and complete. Try a smaller spec if huge. +- OpenAPI URL fetch failed: Check that the URL returns raw JSON/YAML (not HTML), is publicly accessible, and does not require authentication; otherwise download and upload the file. +- No actions shown: Some tasks return explanations only. That’s expected for Explain/Docs. +- Changes didn’t apply: Ensure a request is selected and re-run the action. Use “Apply to Selected” vs “Create New Request” appropriately. +- Documentation file not found: Confirm your Downloads folder is writable; retry or use Copy instead. + +--- + +## Frequently Asked Questions +- Does Dashbot send my data elsewhere? It uses the AI provider you configured to generate text. Your requests/responses may be included in prompts. Review your provider’s privacy policy and avoid sharing secrets. +- Can I undo a fix? Use request history or manually revert fields. Consider “Create New Request” to keep the original unchanged. +- Can I mix steps (e.g., import cURL, then debug)? Yes. Dashbot keeps the session per selected request. diff --git a/doc/user_guide/images/dashbot/dashbot_codegen.png b/doc/user_guide/images/dashbot/dashbot_codegen.png new file mode 100644 index 00000000..50ce90db Binary files /dev/null and b/doc/user_guide/images/dashbot/dashbot_codegen.png differ diff --git a/doc/user_guide/images/dashbot/dashbot_codegen_res_1.png b/doc/user_guide/images/dashbot/dashbot_codegen_res_1.png new file mode 100644 index 00000000..0117903c Binary files /dev/null and b/doc/user_guide/images/dashbot/dashbot_codegen_res_1.png differ diff --git a/doc/user_guide/images/dashbot/dashbot_codegen_res_2.png b/doc/user_guide/images/dashbot/dashbot_codegen_res_2.png new file mode 100644 index 00000000..853e0f21 Binary files /dev/null and b/doc/user_guide/images/dashbot/dashbot_codegen_res_2.png differ diff --git a/doc/user_guide/images/dashbot/dashbot_curl_apply.png b/doc/user_guide/images/dashbot/dashbot_curl_apply.png new file mode 100644 index 00000000..84068879 Binary files /dev/null and b/doc/user_guide/images/dashbot/dashbot_curl_apply.png differ diff --git a/doc/user_guide/images/dashbot/dashbot_curl_paste.png b/doc/user_guide/images/dashbot/dashbot_curl_paste.png new file mode 100644 index 00000000..2a6f1f26 Binary files /dev/null and b/doc/user_guide/images/dashbot/dashbot_curl_paste.png differ diff --git a/doc/user_guide/images/dashbot/dashbot_curl_result.png b/doc/user_guide/images/dashbot/dashbot_curl_result.png new file mode 100644 index 00000000..be9e0d2b Binary files /dev/null and b/doc/user_guide/images/dashbot/dashbot_curl_result.png differ diff --git a/doc/user_guide/images/dashbot/dashbot_debug_error.png b/doc/user_guide/images/dashbot/dashbot_debug_error.png new file mode 100644 index 00000000..06c1b16f Binary files /dev/null and b/doc/user_guide/images/dashbot/dashbot_debug_error.png differ diff --git a/doc/user_guide/images/dashbot/dashbot_debug_result.png b/doc/user_guide/images/dashbot/dashbot_debug_result.png new file mode 100644 index 00000000..72d46aff Binary files /dev/null and b/doc/user_guide/images/dashbot/dashbot_debug_result.png differ diff --git a/doc/user_guide/images/dashbot/dashbot_documentation.png b/doc/user_guide/images/dashbot/dashbot_documentation.png new file mode 100644 index 00000000..2fb54a41 Binary files /dev/null and b/doc/user_guide/images/dashbot/dashbot_documentation.png differ diff --git a/doc/user_guide/images/dashbot/dashbot_env_vars.png b/doc/user_guide/images/dashbot/dashbot_env_vars.png new file mode 100644 index 00000000..7a15a95e Binary files /dev/null and b/doc/user_guide/images/dashbot/dashbot_env_vars.png differ diff --git a/doc/user_guide/images/dashbot/dashbot_explanation.png b/doc/user_guide/images/dashbot/dashbot_explanation.png new file mode 100644 index 00000000..8d827b0e Binary files /dev/null and b/doc/user_guide/images/dashbot/dashbot_explanation.png differ diff --git a/doc/user_guide/images/dashbot/dashbot_fab.png b/doc/user_guide/images/dashbot/dashbot_fab.png new file mode 100644 index 00000000..323333fe Binary files /dev/null and b/doc/user_guide/images/dashbot/dashbot_fab.png differ diff --git a/doc/user_guide/images/dashbot/dashbot_no_request.png b/doc/user_guide/images/dashbot/dashbot_no_request.png new file mode 100644 index 00000000..dbec2ca8 Binary files /dev/null and b/doc/user_guide/images/dashbot/dashbot_no_request.png differ diff --git a/doc/user_guide/images/dashbot/dashbot_openapi_file_picker.png b/doc/user_guide/images/dashbot/dashbot_openapi_file_picker.png new file mode 100644 index 00000000..6f7dc67c Binary files /dev/null and b/doc/user_guide/images/dashbot/dashbot_openapi_file_picker.png differ diff --git a/doc/user_guide/images/dashbot/dashbot_openapi_response.png b/doc/user_guide/images/dashbot/dashbot_openapi_response.png new file mode 100644 index 00000000..5e8eeeed Binary files /dev/null and b/doc/user_guide/images/dashbot/dashbot_openapi_response.png differ diff --git a/doc/user_guide/images/dashbot/dashbot_openapi_route_selection.png b/doc/user_guide/images/dashbot/dashbot_openapi_route_selection.png new file mode 100644 index 00000000..d09f8fb2 Binary files /dev/null and b/doc/user_guide/images/dashbot/dashbot_openapi_route_selection.png differ diff --git a/doc/user_guide/images/dashbot/dashbot_openapi_task.png b/doc/user_guide/images/dashbot/dashbot_openapi_task.png new file mode 100644 index 00000000..429ba0f9 Binary files /dev/null and b/doc/user_guide/images/dashbot/dashbot_openapi_task.png differ diff --git a/doc/user_guide/images/dashbot/dashbot_pop_up.png b/doc/user_guide/images/dashbot/dashbot_pop_up.png new file mode 100644 index 00000000..14414859 Binary files /dev/null and b/doc/user_guide/images/dashbot/dashbot_pop_up.png differ diff --git a/doc/user_guide/images/dashbot/dashbot_tab_view.png b/doc/user_guide/images/dashbot/dashbot_tab_view.png new file mode 100644 index 00000000..5366d6e5 Binary files /dev/null and b/doc/user_guide/images/dashbot/dashbot_tab_view.png differ diff --git a/doc/user_guide/images/dashbot/dashbot_tasks.png b/doc/user_guide/images/dashbot/dashbot_tasks.png new file mode 100644 index 00000000..005ced06 Binary files /dev/null and b/doc/user_guide/images/dashbot/dashbot_tasks.png differ diff --git a/doc/user_guide/images/dashbot/dashbot_tests.png b/doc/user_guide/images/dashbot/dashbot_tests.png new file mode 100644 index 00000000..5783aea8 Binary files /dev/null and b/doc/user_guide/images/dashbot/dashbot_tests.png differ diff --git a/doc/user_guide/images/dashbot/dashbot_tests_res.png b/doc/user_guide/images/dashbot/dashbot_tests_res.png new file mode 100644 index 00000000..e90d1d68 Binary files /dev/null and b/doc/user_guide/images/dashbot/dashbot_tests_res.png differ