wip: cast parameters with json content-type

[albertored]

Hello, I'm trying to fix #349

At the moment I'm am able to correctly cast parameters that are encoded as JSON but I have some questions to understand how you think is better to proceed:

• should I create a new error type for taking into account situations in which the parameter can not be decoded? (atm I'm using :invalid_format)
• I like your suggestion @mbuhot of registering parsers with something like OpenApiSpex.add_content_parser but I think we should allow it specifically for this situation, thus something like OpenApiSpex.add_parameter_content_parser, in other circumstances we already have Plug.Parsers. What do you think?
• I think we can have some default parameter_content_parsers like the JSON one
• To support parameter_content_parsers registration I only need to pass the information to cast_parameters.ex, where should we store this info? Should we create a new field on the root OpenApi struct?

Tagging also @moxley since it was involved in the original issue, sorry for the noise :-)

[albertored]

Any suggestion on the open points?

[mbuhot]

should I create a new error type for taking into account situations in which the parameter can not be decoded?

:invalid_format seems like a good choice. So long as the message from OpenApiSpex.Cast.Error.message makes sense, eg: "Invalid format. Expected application/json"

registering parsers with something like OpenApiSpex.add_content_parser but I think we should allow it specifically for this situation, thus something like OpenApiSpex.add_parameter_content_parser, in other circumstances we already have Plug.Parsers. What do you think?

Yes that makes sense. If OpenApiSpex is only going to use the supplied parser for handling Parameters (not body), then making that explicit in the function name will help.

I think we can have some default parameter_content_parsers like the JSON one

Yes it's helpful to have one included in the library that can be used as a reference.

To support parameter_content_parsers registration I only need to pass the information to cast_parameters.ex, where should we store this info? Should we create a new field on the root OpenApi struct?

Can we use the extensions facility? For schemas we have x-struct and x-validate to store the names of modules.
The OpenApi struct has the extensions field which could store some data under an "x-parameter-content-parsers" key?

[albertored]

@mbuhot done

Now the OpenApiSpex module exposes the following function

@spec add_parameter_content_parser(
          OpenApi.t(),
          content_type | [content_type],
          parser :: module()
        ) :: OpenApi.t()
        when content_type: String.t() | Regex.t()

A parser can be defined for specific content types (strings that should match exactly) or for regular expressions matching multiple content types.

Exact matches are checked first, then regex ones and finally default ones.

The only default is

%{
  ~r/^application\/.*json.*$/ => OpenApiSpex.OpenApi.json_encoder()
}

[mbuhot]

Thanks @albertored !