If you want multiple operationIds to map yo functions with common names, e.g. "index", "create", "delete", etc.

Hi. Nice library.

I would really like to be able to use something like what this library provides without the direct need for Phoenix.
Some services are too simple for Phoenix features and could depend only on Plug, without direct dependency on Phoenix.

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.

Add list of all known places here:

review how we do it in exonerate, and then copy the strategy for apical

• compile error on not required
• deprecated
• style: matrix
• style: label
• explode: matrix
• explode: label
• schema

• with/without explode
• ok and error
• with parameter

• required
• deprecated
• style (check only simple)
• explode
• schema

make sure that malformed query parameters can give useful information as to what went wrong.

• 299 warning when extra unspecified parameters are a thing
• objects with non-even number of things
• illegal characters

Would there be a way to either

• use https://hexdocs.pm/mix/Mix.Tasks.Compile.Elixir.html#module-external_resource to only recompile the routes when the spec changes
• save the output and only recompile manually when needed

length
read_length
read_timeout

• required
• deprecated
• allowEmptyValue
• style
  • form
  • spaceDelimited
  • pipeDelimited
  • deepObject
  • x-
• explode
• allowReserved
• schema
  • deep schema interpretation

desired attributes:

• generation of operation information should probably punt to separate modules (if possible).
• generation of code should be flexible, not tied to phoenix, and allow for a plug-based strategy