Flasgger header parameters aren't described

Question

I try to implement swagger documentation for the project using flasgger. When I describe body fields - it works ok, but when I try to describe header fields, flasgger doesn't present the description of the parameters on the web.

An example of .yml file for flasgger.

description: Client side interaction with server
consumes:
- "application/json"
parameters:
  - in: header
    name: headers_params
    required: true
    schema:
      id: endpoint_header
      required:
        - session_token
      properties:
        session_token:
          type: string
          description: session token
  - in: body
    name: body_params
    required: true
    schema:
      id: endpoint_body
      required:
        - parameter1
        - parameter2
      properties:
        parameter1:
          type: string
          description: The parameter1 description
        parameter2:
          type: string
          description: The parameter2 description

responses:
  500:
      description: The error on the server side

  200:
      description: Access token for user intercation

And, its what I see on web: enter image description here

What structure of .yml file should I follow to get the session token described in the header as well as body parameters?

Answer 1

It looks like you're using OpenAPI 2.0 syntax. In OAS2, header parameters are described like this:

  - in: header
    name: session_token    # <---- HTTP header name
    required: true
    type: string
    description: session token

Alternatively, authentication-related headers such as session tokens can be described as a security scheme, e.g. as an API key.

swagger: '2.0'
...

securityDefinitions:
  session_token:
    type: apiKey
    in: header
    name: session_token   # <---- HTTP header name

# Add the "security" section either on the root level (if all endpoints
# are secured with this token), or inside individual GET/POST/etc. operations
security:
  - session_token: []