improve: added parameter definition to route openapi

[juneidy]

Hi there,

I've added slight modification to dereference parameters so that my route handler can use that to extract all parameters from req object.

[cdimascio]

@juneidysoo thanks for the PR

can you describe the use case here in more detail?
i'd like to understand why are interested in the parameters schema itself, rather than the parameter values (which can be gotten via req.params)

[juneidy]

Hi @cdimascio ,

I am using the parameters schema to extract all parameters from req.query, req.headers, req.params and req.cookies.

It's just an easier way to make my API compliant to the OpenAPI spec by only taking parameters defined in the spec.

[cdimascio]

assuming im understanding correctly, a better approach may be to use additionalProperties: false in the spec. it will be good to know the use case or where the validator does not provide satisficatory checks for your use case. ideally all validation occurs in the validator, rather than requiring manual validation on the developer side.

[juneidy]

additionalProperties: false works for message body schema.

Let's say I have a schema like:

  /foobar:
    get:
      summary: foobar
      operationId: foobar
      parameters:
        - name: param_i_care_about
          in: header
          required: true
          schema:
            type: string

Sometimes there are extra headers sent to server that I don't mind being sent (e.g. X-Forwarded-For by reverse proxy). But I want to use the parameters list in my schema to filter things that the operation really care about.

I understand that both path can't have unknown param and query is already being checked for unknown param, but headers or cookies generally are pretty relaxed hence why I need the schema to filter things out myself.

[juneidy]

I'll try to fix the test once we agreed whether or not this is a good idea.

[cdimascio]

@juneidysoo thanks for the explanation. this makes sense. ideally, we should handle this within the validator. this way developers do not have to worry about it.

i believe this can be handled similarly to query params. it will likely also require a new option, e.g. allowUnknownHeaders. would you be up for taking a stab at implementing this feature for headers. The implementation should be fairly similar to that of unknown query params. (i suspect, we can reuse a lot that logic).

[juneidy]

i believe this can be handled similarly to query params. it will likely also require a new option, e.g. allowUnknownHeaders. would you be up for taking a stab at implementing this feature for headers. The implementation should be fairly similar to that of unknown query params. (i suspect, we can reuse a lot that logic).

I believe that would cause more issues. Because often case people would have reverse proxy which would generally adds extra headers (e.g. X-Real-IP, X-Forwarded-For, X-Forwarded-Host, X-Forwarded-Proto and X-Forwarded-Path)

In my opinion, those extra headers are fine, and I don't want the validation to fail. Sometimes I do want them, but most of the time they are ignored. Hence the need for parameters list.

[juneidy]

Although alternatively, I could do something like pathParams in the same file (openapi.metadata.ts) where it extracts the parameters to a hash map.

[juneidy]

Hi @cdimascio Following up on what you think of what I have said.

[cdimascio]

@juneidysoo thanks for the details and for continuing to think about this

based on your comment, allowing additional headers (the default behavior) is definitely what you want. your proxy example is a good one.

i see that you'd like more of the validator internals exposed so that you can do this post-filtering, but i'm not yet understanding the benefit of that filtering.

it seems that the request is validated correctly and allows those additional headers e.g. from a proxy

given that it's okay for those headers to pass through, i'd like to get a better idea of why its necessary to perform additional post-filtering?

[juneidy]

What I am trying to do is to perform parameter injection based on the parameter declared in openapi spec.

So that the underlying function that handles the route doesn't need to know where or how to get the parameters.

[cdimascio]

let's try to go with your alternative i.e. the pathParam-like approach. I'm still not certain about this, but let's see how it looks.