This section explains the major API stack upgrade happening on GeoAR.it.
🔧 What’s Going On?
- 🔄 Major refactor: GeoAR.it is migrating from Swashbuckle/Swagger (OpenAPI v2) to Microsoft.OpenAPI and NSwag.
- 🦖 Swashbuckle is out: The old stack is obsolete—no updates, no security patches, stuck on old tech.
- 🚀 Industry shift: Modern tools, AI, and Model Context Protocol expect OpenAPI 3.1 for full compatibility.
- 🔓 Not locked down: Endpoints, models, and docs are changing rapidly and are not yet stable.
- 🛠️ Some things missing: Sample data and familiar docs are temporarily unavailable or incomplete.
- 💡 Want to know the bigger picture? See About GeoAR.it and Me.
Bottom line: Moving fast, fixing what matters, and not pretending the API is “stable” when it isn’t.
This section summarises why the move away from Swashbuckle is necessary.
❓ Why Am I Doing This?
- 🦖 Swashbuckle is obsolete: It’s unmaintained and a security risk.
- 🌍 OpenAPI 3.1 is now standard: Modern tools and AI agents demand it.
- 🏆 Microsoft.OpenAPI and NSwag: The .NET gold standard for API compatibility.
- 🔗 Future proof: This shift lets GeoAR.it work with agent platforms, the MCP ecosystem, and the future Spatial Web.
- ⚠️ Not pretending it’s stable: While in transition, some things will break or go missing.
This section gives the honest current state of the API, endpoints, and docs.
📊 What’s The State Right Now?
- ❌ Swashbuckle is gone.
- ✅ Microsoft.OpenAPI and NSwag are live.
- ♻️ Everything’s in flux: Endpoints, URIs, and models are changing (sometimes daily).
- ⚡ If you develop now, expect churn: Don’t build for production yet!
- 📚 Docs are missing nice-to-haves: No example/sample data in the UI yet. Ask if you need examples.
- 🛑 NuGet package: GeoARIt.Api NuGet package is broken and intentionally unsupported for now.
- 🧰 Need client code? Use live OpenAPI docs for now.
This section is for developers and integrators who want to build on GeoAR.it.
👨💻 For Developers & Integrators
- 🛑 Wait for “contract freeze”: The API will be called “stable” and production-ready after a public notice.
- 🕵️ Track changes here: Keep an eye on /swagger/v1/swagger.json for the current schema.
- ⚡ Not for prod yet: Don’t integrate with mission-critical systems while the API is in flux.
- 🧠 For project philosophy, see About GeoAR.it and Me.
This section lists the next planned actions and priorities for the API migration.
🔜 What’s Next?
- 🧹 Finish rewriting endpoints and cleaning up models.
- 📚 Restore example/sample data to the docs UI.
- 🔄 Fix and relaunch the NuGet package after the API is stable.
- 🔒 Announce when the API is fully versioned and safe to build on.
This section gathers quick links to important resources and documentation.
This section gives a bullet-point summary of the current state and important notes.
🧾 Summary
- 🚀 Moved to NSwag and Microsoft.OpenAPI.
- ♻️ API and docs are changing—don’t treat them as final.
- 📚 Example/sample data in the docs is missing for now (it will return).
- 🛑 NuGet package is dead—wait for the “all clear” before using it.