diff --git a/docs/openapi-servers/faq.mdx b/docs/openapi-servers/faq.mdx new file mode 100644 index 0000000..279b794 --- /dev/null +++ b/docs/openapi-servers/faq.mdx @@ -0,0 +1,167 @@ +--- +sidebar_position: 2 +title: "❓ FAQ" +--- + +#### 🌐 Q: Why isn't my local OpenAPI tool server accessible from the WebUI interface? + +**A:** If your tool server is running locally (e.g. http://localhost:8000), browser-based clients may be restricted from accessing it due to CORS (Cross-Origin Resource Sharing) policies. + +Make sure to explicitly enable CORS headers in your OpenAPI server. For example, if you're using FastAPI, you can add: + +```python +from fastapi.middleware.cors import CORSMiddleware + +app.add_middleware( + CORSMiddleware, + allow_origins=["*"], # or specify your client origin + allow_credentials=True, + allow_methods=["*"], + allow_headers=["*"], +) +``` + +Also, if Open WebUI is served over HTTPS (e.g. https://yourdomain.com), your local server must meet one of the following conditions: + +- Be accessed from the same domain using HTTPS (e.g. https://localhost:8000). +- OR run on localhost (127.0.0.1) to allow browsers to relax security for local development. +- Otherwise, browsers may block insecure requests from HTTPS pages to HTTP APIs due to mixed-content rules. + +To work securely in production over HTTPS, your OpenAPI servers must also be served over HTTPS. + +--- + +#### 🚀 Q: Do I need to use FastAPI for my server implementation? + +**A:** No! While our reference implementations are written using FastAPI for clarity and ease of use, you can use any framework or language that produces a valid OpenAPI (Swagger) specification. Some common choices include: + +- FastAPI (Python) +- Flask + Flask-RESTX (Python) +- Express + Swagger UI (JavaScript/Node) +- Spring Boot (Java) +- Go with Swag or Echo + +The key is to ensure your server exposes a valid OpenAPI schema, and that it communicates over HTTP(S). + +--- + + +#### 🚀 Q: Why choose OpenAPI over MCP? + +**A:** OpenAPI wins over MCP in most real-world scenarios due to its simplicity, tooling ecosystem, stability, and developer-friendliness. Here's why: + +- ✅ **Reuse Your Existing Code**: If you’ve built REST APIs before, you're mostly done—you don’t need to rewrite your logic. Just define a compliant OpenAPI spec and expose your current code as a tool server. + + With MCP, you had to reimplement your tool logic inside a custom protocol layer, duplicating work and increasing the surface area to maintain. + +- 💼 **Less to Maintain & Debug**: OpenAPI fits naturally into modern dev workflows. You can test endpoints with Postman, inspect logs with built-in APIs, troubleshoot easily with mature ecosystem tools—and often without modifying your core app at all. + + MCP introduced new layers of transport, schema parsing, and runtime quirks, all of which had to be debugged manually. + +- 🌍 **Standards-Based**: OpenAPI is widely adopted across the tech industry. Its well-defined structure means tools, agents, and servers can interoperate immediately, without needing special bridges or translations. + +- 🧰 **Better Tooling**: There’s an entire universe of tools that support OpenAPI—automatic client/server generation, documentation, validation, mocking, testing, and even security audit tools. + +- 🔐 **First-Class Security Support**: OpenAPI includes native support for things like OAuth2, JWTs, API Keys, and HTTPS—making it easier to build secure endpoints with common libraries and standards. + +- 🧠 **More Devs Already Know It**: Using OpenAPI means you're speaking a language already familiar to backend teams, frontend developers, DevOps, and product engineers. There’s no learning curve or costly onboarding required. + +- 🔄 **Future-Proof & Extensible**: OpenAPI evolves with API standards and remains forward-compatible. MCP, by contrast, was bespoke and experimental—often requiring changes as the surrounding ecosystem changed. + +🧵 Bottom line: OpenAPI lets you do more with less effort, less code duplication, and fewer surprises. It’s a production-ready, developer-friendly route to powering LLM tools—without rebuilding everything from scratch. + + +--- + +#### 🔐 Q: How do I secure my OpenAPI tool server? + +**A:** OpenAPI supports industry-standard security mechanisms like: + +- OAuth 2.0 +- API Key headers +- JWT (JSON Web Token) +- Basic Auth + +Use HTTPS in production to encrypt data in transit, and restrict endpoints with proper auth/authz methods as appropriate. You can incorporate these directly in your OpenAPI schema using the securitySchemes field. +--- + +#### ❓ Q: What kind of tools can I build using OpenAPI tool servers? + +**A:** If it can be exposed via a REST API, you can build it. Common tool types include: + +- Filesystem operations (read/write files, list directories) +- Git and document repository access +- Database querying or schema exploration +- Web scrapers or summarizers +- External SaaS integrations (e.g., Salesforce, Jira, Slack) +- LLM-attached memory stores / RAG components +- Secure internal microservices exposed to your agent + +--- + +#### 🔌 Q: Can I run more than one tool server at the same time? + +**A:** Absolutely. Each tool server runs independently and exposes its own OpenAPI schema. Your agent configuration can point to multiple tool servers, allowing you to mix and match based on need. + +There's no limit—just ensure each server runs on its own port or address and is reachable by the agent host. + +--- + +#### 🧪 Q: How do I test a tool server before linking it to an LLM agent? + +**A:** You can test your OpenAPI tool servers using: + +- Swagger UI or ReDoc (built into FastAPI by default) +- Postman or Insomnia +- curl or httpie from the command line +- Python’s requests module +- OpenAPI validators and mockers + +Once validated, you can register the tool server with an LLM agent or through Open WebUI. + +--- + +#### 🛠️ Q: Can I extend or customize the reference servers? + +**A:** Yes! All servers in the servers/ directory are built to be simple templates. Fork and modify them to: + +- Add new endpoints and business logic +- Integrate authentication +- Change response formats +- Connect to new services or internal APIs +- Deploy via Docker, Kubernetes, or any cloud host + +--- + +#### 🌍 Q: Can I run OpenAPI tool servers on cloud platforms like AWS or GCP? + +**A:** Yes. These servers are plain HTTP services. You can deploy them as: + +- AWS Lambda with API Gateway (serverless) +- EC2 or GCP Compute Engine instances +- Kubernetes services in GKE/EKS/AKS +- Cloud Run or App Engine +- Render, Railway, Heroku, etc. + +Just make sure they’re securely configured and publicly reachable (or VPN'd) if needed by the agent or user. + +--- + +#### 🧪 Q: What if I have an existing MCP server? + +**A:** Great news! You can use the mcp-proxy provided in our repo to expose your existing MCP-based tool server as a standard OpenAPI-compatible server. This allows for seamless integration with Open WebUI or other OpenAPI-based agents without needing to rewrite existing logic. + +Refer to the optional MCP bridge section in the main docs for setup instructions. + +--- + +#### 🗂️ Q: Can one OpenAPI server implement multiple tools? + +**A:** Yes. A single OpenAPI server can offer multiple related capabilities grouped under different endpoints. For example, a document server may provide search, upload, OCR, and summarization—all within one schema. + +You can also modularize completely by creating one OpenAPI server per tool if you prefer isolation and flexibility. + +--- + +🙋 Have more questions? Visit the GitHub discussions for help and feedback from the community: +👉 [Community Discussions](https://github.com/open-webui/openapi-servers/discussions)