Move OpenAPI UI hosting into Toolkit while keeping generated specs inside modules

[armanist]

Summary

Refactor OpenAPI integration so Toolkit becomes the single host for the OpenAPI UI, routes, and shared Swagger assets, while generated OpenAPI specs continue to live inside the modules they document.

Why

Current OpenAPI integration mixes shared and module-specific responsibilities.

Today:

• the shared OpenAPI HTML view lives in the project’s shared/views/openapi
• Swagger UI assets are published into a shared public asset directory
• per-module openapi/docs and openapi/spec routes are injected into each module
• generated OpenAPI specs live inside each module under resources/openapi/spec.json

This creates an awkward split where a shared UI is accessed through module-local route publication.

Toolkit is already the framework’s developer-facing web UI for features such as:

• database access
• logs
• emails
• module management

That makes Toolkit the better place to host OpenAPI documentation access centrally.

Goal

Make Toolkit the central OpenAPI UI host while preserving module ownership of generated specs.

Proposed Direction

Toolkit should own OpenAPI UI hosting

Toolkit should become the single place that owns:

• OpenAPI pages/views
• OpenAPI routes
• shared Swagger UI assets

OpenAPI should no longer rely on shared non-Toolkit HTML views or per-module docs route injection for UI access.

Generated specs should remain module-owned

Generated specs should continue to live inside each documented module:

• modules/{Module}/resources/openapi/spec.json

This keeps OpenAPI output aligned with the module that owns the API.

Toolkit should discover only generated specs

Toolkit should list only modules that already have generated OpenAPI spec files.

Discovery should be based on the presence of:

• resources/openapi/spec.json

Toolkit should not try to infer availability only from annotation sources.

Toolkit should serve specs through Toolkit routes

Toolkit should expose module OpenAPI specs through Toolkit-owned routes rather than relying on direct file access or module-local openapi/spec routes.

Generation command should stop owning shared UI concerns

The current module-targeted OpenAPI command should no longer publish shared UI assets or inject module docs routes.

Its responsibility should be reduced to module-specific spec generation.

Because of that narrower responsibility, the command name should be reviewed and likely changed from:

• install:openapi

to something more accurate such as:

• openapi:generate

A backward-compatible alias can be considered separately if needed.

UX Expectations

• if Toolkit is installed but no module has a generated spec yet, Toolkit should show an empty state rather than a broken page
• users must run the spec generation command for a module before that module appears in Toolkit’s OpenAPI UI

Acceptance Criteria

• Toolkit owns the OpenAPI UI entry point
• Toolkit owns the OpenAPI routes/pages
• Toolkit owns the shared Swagger UI asset usage
• generated specs remain stored inside each module under resources/openapi/spec.json
• Toolkit lists only modules that already have generated spec files
• Toolkit serves module specs through Toolkit routes
• per-module OpenAPI docs route injection is no longer required for the Toolkit-hosted flow
• the module-targeted OpenAPI command is reduced to spec-generation responsibility and its command naming is reviewed accordingly

Notes

Relevant code:

• src/Console/Commands/OpenApiCommand.php
• src/Console/Commands/InstallToolkitCommand.php
• src/Module/Templates/Toolkit
• project shared/views/openapi/openapi.php
• project public/assets/OpenApiUi
• module resources/openapi/spec.json
• module Controllers/OpenApi/*

This ticket should be treated as the first OpenAPI/Toolkit integration step. It centralizes OpenAPI hosting in Toolkit without changing module ownership of generated specs.