Option to generate routes across multiple controllers

gmile commented 1 year ago

Question

Asking since this wasn't immediately clear from the documentation, but how does one use the single .json/.yaml schema to generate routes to actions across multiple controllers?

Based on the current example from the docs, it looks like the app would have to have a single controller only?

Apical.router_from_file(
  "path/to/openapi.yaml",
  controller: MyProjectWeb.ApiController
)

Or alternatively, split the OpenAPI schema file into multiple files, then invoke Apical.router_from_file/2 multiple times referring to different file and each time a different controller.

Instead, would it not be more convenient to have an option to generate routes for many controllers/actions from the schema - for example, to improve code organisation: one could have a single .json/.yaml schema, and multiple controller files. I believe having multiple controller files is somewhat a de-facto standard approach of code organisation, for example, in projects using Phoenix framework.

For example, imaging OpenAPI Schema describes two families of routes: posts and comments:

GET /posts
POST /posts
PUT /posts/:id
GET /posts/:id
DELETE /posts/:id
GET /posts/:post_id/comments
POST /posts/:post_id/comments
PUT /comments/:id
GET /comments/:id
DELETE /comments/:id

It would be nice to have Apical generate routes to actions from two controllers:

GET /posts                    -> PostController#index
POST /posts                   -> PostController#create
PUT /posts/:id                -> PostController#update
GET /posts/:id                -> PostController#show
DELETE /posts/:id             -> PostController#destroy
GET /posts/:post_id/comments  -> CommentController#index
POST /posts/:post_id/comments -> CommentController#craete
PUT /comments/:id             -> CommentController#update
GET /comments/:id             -> CommentController#show
DELETE /comments/:id          -> CommentController#destroy

Proposed solution

I think one way to achieve this could be for Apical to derive the names of controller and action from based on some conventional information of the operation.

For example, it could be convenient to use operationId to store the a value of PostController#index string. Then, Apical would use this string to build a route to the said controller:

openapi: 3.1.0
  info:
    title: My API
    version: 1.0.0
  paths:
    "/posts":
      post:
        operationId: "PostController#create"
        responses:
          "200":
            description: OK
# ...

One problem with this approach could be that, at the compilation time, all controller modules must already exist.