[TECH] Review OpenAPI documentation approach

[spydmobile]

Context

swagger-jsdoc@6.2.8 is unmaintained (last update Jan 2023) and pulls deprecated dependencies:

• glob@7.1.6
• lodash.mergewith
• swagger-parser@10.0.3 → z-schema → lodash.get, lodash.isequal

These are not security issues, just deprecation warnings. The packages work fine.

Current State

• 27 @openapi annotations across 6 route files
• Serves interactive docs at /api/docs
• Serves raw spec at /api/openapi.json

Options to Evaluate

1. Keep as-is - Accept deprecation warnings, they're harmless
2. Manual spec + swagger-ui-express only - Extract annotations to standalone openapi.yaml, drop swagger-jsdoc
3. Drop interactive docs entirely - Export static spec at build time, let consumers use their own tools
4. Alternative library - If a maintained lightweight alternative emerges

Decision Needed

• Is interactive API documentation actually used/valued?
• Worth the migration effort to eliminate warnings?

Related

• [SEC] Replace tokml with GDAL for GeoJSON→KML conversion #123 fixed the actual security issue (tokml → minimatch vulnerability)

[nealmcloughlin]

Security vulnerability has been removed. Refine this task for Milestone 7.