Document, how headers are passed to the methods about connexion HOT 6 CLOSED

There is no special trick here: you can simply access the Flask headers via "flask.request.headers", see http://flask.pocoo.org/docs/0.10/api/#flask.Request.headers

from connexion.

This way one can say, that all parameters are accessible with this "trick".

Headers are 1st class citizens in Swagger and are typed as well. So it seems that they should be pushed into the method as a parameter and typing should be checked and probably values converted, just like for the normal parameters.

from connexion.

That would be a nice feature if it was possible.

from connexion.

@valgog ok, I agree. I would define most headers not in the Swagger file (as they are usually technical metadata), but I see that there are valid use cases for using headers as first class citizens as defined in Swagger spec.

from connexion.

I agree with @hjacobs here - in that we wouldn't want to define every header. Rather just have the option to define one or more important headers in the spec. If a header is specified, then validating it would be great. Ideally this would work in both directions - request and response headers.

I had an example recently where in my spec I want to specify that a Location header is returned for a POST operation. We have the functionality now to return that extra header from the view. It would be great if we could verify the header is returned and possibly validate the format too. I didn't think about this when I made my pull request unfortunately.

I could try and take a look at this if people wanted this feature?

from connexion.

I don't really see a use case for passing to controllers. Headers are to be picked up by the infrastructure (gateways and the framework), usually. I realize you can specify in: header according to the docs, but that doesn't necessarily mean they should be passed to controllers. They should be validated and type casted though.

The Swagger spec is IMO a bit vague on header params. I mean this (from the spec):

name: token
in: header
description: token to be passed as a header
required: true
type: array
items:
  type: integer
  format: int64
collectionFormat: csv

Is fine, except for the name. Are we not using the "X-" extension prefix for HTTP header names? Dash-separated-upper-case-first? Or are we leaving out a transformation from header name to parameter name? In the latter case the interface would be incomplete so we have to assume the former. So we're talking:

name: X-Token
in: header
description: token to be passed as a header
required: true
type: array
items:
  type: integer
  format: int64
collectionFormat: csv

So we could strip X-, convert the rest to snake-case and pass it to the function. But what you probably want is to have it picked up by some middleware (eg Flask decorators), instead.

To summarize: yes to validate and cast, but using the result in a decorator would most likely be much more useful than as an argument.

from connexion.