Flasgger配置的header参数描述无法在Swagger文档页展示如何解决？

问题原因 #

你当前的YAML配置不符合Swagger 2.0（Flasgger默认适配的OpenAPI版本）的Header参数定义规范：Header类型的参数不支持通过schema字段定义嵌套对象结构，Swagger UI不会解析header参数schema下的子字段属性，因此session_token的描述无法正常渲染。

修正后的YAML配置 #

description: 客户端与服务端交互接口
consumes:
- "application/json"
parameters:
  # 单独定义每个header参数，不要嵌套在统一schema中
  - in: header
    name: session_token
    required: true
    type: string
    description: 会话凭证
  - in: body
    name: body_params
    required: true
    schema:
      id: endpoint_body
      required:
        - parameter1
        - parameter2
      properties:
        parameter1:
          type: string
          description: 参数1的说明
        parameter2:
          type: string
          description: 参数2的说明

responses:
  500:
      description: 服务端内部错误
  200:
      description: 用户交互用的访问凭证

核心修改说明 #

• 移除原配置中统一包裹header字段的headers_params参数项，每个header参数（这里为session_token）需单独作为parameters数组的独立元素配置
• Header参数的type、description、required属性直接定义在参数根层级即可，无需额外嵌套schema字段
• Body参数的原有配置逻辑无需调整，body类型参数本身支持通过schema定义复杂嵌套结构体

内容的提问来源于stack exchange，提问作者Alex Kay