add :default option in parameters of operation

[bangalcat]

Hello, I've recently used this library and it's awesome! Really appreciate for you.

I have a tiny proposal. I've realized that you provide some convenience for defining operations, like in parameters, I can use type: :integer instead of %Schema{}. It is really useful! But I often need a default value for that parameter. So I think it would be great if there is another convenient option default in parameters.

Though I cannot totally sure about that, want to know your opinions. Thanks again!

[mbuhot]

Hi @bangalcat, thanks for the suggestion. I'm considering a few options for this.

Using the examples from https://swagger.io/docs/specification/describing-parameters/#default

1) Forward all additional opts from Parameter to Schema

  operation :search,
    summary: "Search for items",
    parameters: [
      offset: [
        in: :query,
        type: :integer,
        minimum: 0,
        default: 0,
        required: false,
        description: "The number of items to skip before starting to collect the result set."
      ],
      limit: [
        in: :query,
        type: :integer,
        minimum: 1,
        maximum: 100,
        default: 20,
        required: false,
        description: "The number of items to return."
      ]
    ],

This intentionally blurs the line between Parameter and Schema to reduce nesting. I'm currently leaning towards this option.

2) Keyword schema

  operation :search,
    summary: "Search for items",
    parameters: [
      offset: [
        in: :query,
        required: false,
        description: "The number of items to skip before starting to collect the result set.",
        schema: [
          type: :integer,
          minimum: 0,
          default: 0
        ]
      ],
      limit: [
        in: :query,
        required: false,
        description: "The number of items to return.",
        schema: [
          type: :integer,
          minimum: 1,
          maximum: 100,
          default: 20
        ]
      ]
    ]

This reduces some noise when describing the schema, although it introduces inconsistency with how schemas are usually declared and doesn't help to reduce nesting.

3) Struct schema

  operation :search,
    summary: "Search for items",
    parameters: [
      offset: [
        in: :query,
        required: false,
        description: "The number of items to skip before starting to collect the result set.",
        schema: %Schema{
          type: :integer,
          minimum: 0,
          default: 0
        }
      ],
      limit: [
        in: :query,
        required: false,
        description: "The number of items to return.",
        schema: %Schema{
          type: :integer,
          minimum: 1,
          maximum: 100,
          default: 20
        }
      ]
    ],

For comparison, explicit struct schemas.

[bangalcat]

Hi, @mbuhot . Thanks for the reply! I also think option 1 is better. I guess we should receive either one schema with no other schema related fields, or some schema fields which must includes type.
Perhaps I can send a PR, if you don't mind 😃

[mbuhot]

Paging @zorbash and @moxley for thoughts or alternative suggestions on making a change to the DSL.

[moxley]

My concern with option #1 is that it makes it harder for people reading the code to follow what's going on. OpenApiSpex introduces a layer on top of OpenAPI that users of the library have to go through to map to the OpenAPI spec. If you're already very well-versed in OpenAPI, then adding conveniences like option #1 probably isn't a problem, and the benefits outweigh the drawbacks. But if you're writing software that's being maintained by developers with varied familiarity with OpenAPI, any convenience added like this makes understanding particularly difficult for those who aren't well-versed in OpenAPI.

You could argue that when we introduced the controller operations DSL (especially the tuple-backed data nested data structures within the operation), that added more translation overhead. But I think that the convenience gained was large, and I think it had a major role in making this library as popular as it is today.

So, my question is: how much benefit would option #1 bring to you? Is it like "Oh, that would be cool" kind of benefit, or is it "I have so many parameters, each with defaults, and this feature would really make my life easier" kind of benefit?

At the same time, I don't have strong feelings about this. Maybe this feature can be documented in some remote corner of the API docs, so that power users can find it and use it.

And for option #2, I agree with what @mbuhot said about it.

[bangalcat]

Hmm.. I get your point. So let me explain how I've reached this idea.

I'm working at large project and our old phoenix project is quite big. So our controllers are also average big. Hence I didn't want to put operations into controllers and I separate operation files(using this method).
I wanted to make the dependencies of operation files as small as possible, so I usually declare only some aliases of some schema modules related to request_body or response schemas. Because I didn't want to let my coworkers use OpenApiSpex.Schema module directly in operation files, I also made some common schema modules and helper functions.

So far so good! All request body and responses are explicit schemas. However, the thing sometimes bothers me and my coworkers is parameter in operation. My coworkers didn't understand at first why they need to use schema in parameters, because if they don't need additional options(like default), they just used type, description, required. And in many cases that was enough.

IMHO, it might be less confusing if there were no convenient methods in parameters.

On the other hand, in my case, default field is quite used a lot, so I've suggested that also to support it would be great.

But I guess that I still can make my own helper functions which return schema struct for that cases. Thus technically it may be "that would be cool" kind of things.

I'm not sure if I explained it well 😅 .