未描述Flasgger标头参数

Question

我尝试使用 flasgger 为项目实现 swagger 文档。当我描述正文字段时 - 它工作正常，但是当我尝试描述标题字段时，flasgger 不会在网络上显示参数的描述。

flasgger 的 .yml 文件示例。

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

而且，这是我在网上看到的： enter image description here

我应该遵循什么结构的 .yml 文件来获取标头中描述的会话令牌以及正文参数？

Answer 1

看起来您使用的是 OpenAPI 2.0 语法。在 OAS2 中，header parameters 是这样描述的：

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

另外，与身份验证相关的标头（例如会话令牌）可以描述为 security scheme，例如作为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: []