请求中的 Swagger OpenAPI 3.0 空身份验证 header

Swagger OpenAPI 3.0 empty authentication header in request

我使用 TypeScript 的 tsoa 生成了下面列出的 swagger.json。但是,当我从 swagger 向授权菜单添加访问令牌并向我的端点之一发出请求时,我希望访问令牌位于 x-access-token header 内。但是,header 没有添加到我的请求中。我需要更改我的 swagger.json 什么才能启用授权 header?

Swagger.json

    {
   "components":{
      "examples":{
         
      },
      "headers":{
         
      },
      "parameters":{
         
      },
      "requestBodies":{
         
      },
      "responses":{
         
      },
      "schemas":{
         "Parameter":{
            "properties":{
               "property":{
                  "type":"string"
               },
               "value":{
                  "type":"string"
               }
            },
            "required":[
               "property",
               "value"
            ],
            "type":"object",
            "additionalProperties":false
         },
         "Header":{
            "properties":{
               "key":{
                  "type":"string"
               },
               "value":{
                  "type":"string"
               }
            },
            "required":[
               "key",
               "value"
            ],
            "type":"object",
            "additionalProperties":false
         },
         "AuthenticationEndpoint":{
            "properties":{
               "host":{
                  "type":"string"
               },
               "method":{
                  "type":"string"
               },
               "requestLine":{
                  "type":"string"
               },
               "queryParameters":{
                  "items":{
                     "$ref":"#/components/schemas/Parameter"
                  },
                  "type":"array"
               },
               "headers":{
                  "items":{
                     "$ref":"#/components/schemas/Header"
                  },
                  "type":"array"
               },
               "body":{
                  "properties":{
                     
                  },
                  "type":"object"
               }
            },
            "required":[
               "host",
               "method",
               "requestLine"
            ],
            "type":"object",
            "additionalProperties":false
         },
         "Endpoint":{
            "properties":{
               "host":{
                  "type":"string"
               },
               "method":{
                  "type":"string"
               },
               "requestLine":{
                  "type":"string"
               },
               "queryParameters":{
                  "items":{
                     "$ref":"#/components/schemas/Parameter"
                  },
                  "type":"array"
               },
               "headers":{
                  "items":{
                     "$ref":"#/components/schemas/Header"
                  },
                  "type":"array"
               },
               "body":{
                  "properties":{
                     
                  },
                  "type":"object"
               },
               "secured":{
                  "type":"boolean"
               },
               "authenticationHeader":{
                  "type":"string"
               },
               "authenticationAction":{
                  "$ref":"#/components/schemas/AuthenticationEndpoint"
               }
            },
            "required":[
               "host",
               "method",
               "requestLine"
            ],
            "type":"object",
            "additionalProperties":false
         },
         "Order":{
            "properties":{
               "_id":{
                  "type":"string"
               },
               "command":{
                  "type":"string"
               },
               "action":{
                  "$ref":"#/components/schemas/Endpoint"
               }
            },
            "required":[
               "command",
               "action"
            ],
            "type":"object",
            "additionalProperties":false
         },
         "ApplicationUser":{
            "properties":{
               "_id":{
                  "type":"string"
               },
               "email":{
                  "type":"string"
               },
               "password":{
                  "type":"string"
               },
               "firstname":{
                  "type":"string"
               },
               "lastname":{
                  "type":"string"
               },
               "role":{
                  "type":"string"
               },
               "language":{
                  "type":"string"
               },
               "commands":{
                  "items":{
                     "$ref":"#/components/schemas/Order"
                  },
                  "type":"array"
               }
            },
            "required":[
               "email",
               "password",
               "firstname"
            ],
            "type":"object",
            "additionalProperties":false
         }
      },
      "securitySchemes":{
         "bearer":{
            "type":"apiKey",
            "name":"x-access-token",
            "in":"header"
         }
      }
   },
   "info":{
      "title":"custom_voice_commands",
      "version":"1.0.0",
      "description":"<b>This API facilitates custom voice commands to execute the corresponding configured API endpoint</b>",
      "license":{
         "name":"ISC"
      },
      "contact":{
         
      }
   },
   "openapi":"3.0.0",
   "paths":{
      "/admin/register":{
         "post":{
            "operationId":"RegisterAdmin",
            "responses":{
               "200":{
                  "description":"Ok",
                  "content":{
                     "application/json":{
                        "schema":{
                           "type":"string"
                        }
                     }
                  }
               }
            },
            "tags":[
               "Admin"
            ],
            "security":[
               
            ],
            "parameters":[
               
            ],
            "requestBody":{
               "required":true,
               "content":{
                  "application/json":{
                     "schema":{
                        "$ref":"#/components/schemas/ApplicationUser"
                     }
                  }
               }
            }
         }
      },
      "/admin/commands/create":{
         "post":{
            "operationId":"CreateCommand",
            "responses":{
               "201":{
                  "description":"Created",
                  "content":{
                     "application/json":{
                        "schema":{
                           
                        }
                     }
                  }
               }
            },
            "tags":[
               "Admin Commands"
            ],
            "security":[
               {
                  "jwt":[
                     "admin"
                  ]
               }
            ],
            "parameters":[
               
            ],
            "requestBody":{
               "required":true,
               "content":{
                  "application/json":{
                     "schema":{
                        "$ref":"#/components/schemas/Order"
                     }
                  }
               }
            }
         }
      },
      "/admin/commands/update/{orderId}":{
         "put":{
            "operationId":"UpdateCommand",
            "responses":{
               "204":{
                  "description":"No content"
               }
            },
            "tags":[
               "Admin Commands"
            ],
            "security":[
               {
                  "jwt":[
                     "admin"
                  ]
               }
            ],
            "parameters":[
               {
                  "in":"path",
                  "name":"orderId",
                  "required":true,
                  "schema":{
                     "type":"string"
                  }
               }
            ],
            "requestBody":{
               "required":true,
               "content":{
                  "application/json":{
                     "schema":{
                        "$ref":"#/components/schemas/Order"
                     }
                  }
               }
            }
         }
      },
      "/admin/commands/delete/{orderId}":{
         "delete":{
            "operationId":"DeleteCommand",
            "responses":{
               "204":{
                  "description":"No content"
               }
            },
            "tags":[
               "Admin Commands"
            ],
            "security":[
               {
                  "jwt":[
                     "admin"
                  ]
               }
            ],
            "parameters":[
               {
                  "in":"path",
                  "name":"orderId",
                  "required":true,
                  "schema":{
                     "type":"string"
                  }
               }
            ]
         }
      },
      "/orders/execute-voice-command":{
         "post":{
            "operationId":"ExecuteCommand",
            "responses":{
               "200":{
                  "description":"Ok",
                  "content":{
                     "application/json":{
                        "schema":{
                           
                        }
                     }
                  }
               }
            },
            "tags":[
               "Orders"
            ],
            "security":[
               
            ],
            "parameters":[
               
            ]
         }
      },
      "/orders":{
         "get":{
            "operationId":"GetOrders",
            "responses":{
               "200":{
                  "description":"Ok",
                  "content":{
                     "application/json":{
                        "schema":{
                           "items":{
                              "$ref":"#/components/schemas/Order"
                           },
                           "type":"array"
                        }
                     }
                  }
               }
            },
            "tags":[
               "Orders"
            ],
            "security":[
               
            ],
            "parameters":[
               
            ]
         }
      },
      "/orders/{orderId}":{
         "get":{
            "operationId":"GetOrder",
            "responses":{
               "200":{
                  "description":"Ok",
                  "content":{
                     "application/json":{
                        "schema":{
                           "$ref":"#/components/schemas/Order"
                        }
                     }
                  }
               }
            },
            "tags":[
               "Orders"
            ],
            "security":[
               
            ],
            "parameters":[
               {
                  "in":"path",
                  "name":"orderId",
                  "required":true,
                  "schema":{
                     "type":"string"
                  }
               }
            ]
         }
      },
      "/user/register":{
         "post":{
            "operationId":"RegisterUser",
            "responses":{
               "200":{
                  "description":"Ok",
                  "content":{
                     "application/json":{
                        "schema":{
                           "type":"string"
                        }
                     }
                  }
               }
            },
            "tags":[
               "User"
            ],
            "security":[
               {
                  "jwt":[
                     "admin"
                  ]
               }
            ],
            "parameters":[
               
            ],
            "requestBody":{
               "required":true,
               "content":{
                  "application/json":{
                     "schema":{
                        "$ref":"#/components/schemas/ApplicationUser"
                     }
                  }
               }
            }
         }
      },
      "/commands/execute":{
         "post":{
            "description":"<b>Upload a command as a mono recording formatted to a wav file with 16kHz</b> <br> <b>The endpoint corresponding to the command will be executed.</b>",
            "requestBody":{
               "required":true,
               "content":{
                  "multipart/form-data":{
                     "schema":{
                        "type":"object",
                        "properties":{
                           "voiceCommand":{
                              "type":"string",
                              "format":"binary"
                           }
                        }
                     }
                  }
               }
            }
         }
      }
   },
   "servers":[
      {
         "url":"/"
      }
   ]
}

更新以下swagger.json解决了我的问题(由于字符限制删除了模式)

    {
   "components":{
      "securitySchemes":{
         "jwt":{
            "type":"apiKey",
            "name":"x-access-token",
            "in":"header"
         }
      }
   },
   "info":{
      "title":"custom_voice_commands",
      "version":"1.0.0",
      "description":"<b>This API facilitates custom voice commands to execute the corresponding configured API endpoint</b>",
      "license":{
         "name":"ISC"
      },
      "contact":{
         
      }
   },
   "openapi":"3.0.0",
   "paths":{
      "/admin/register":{
         "post":{
            "operationId":"RegisterAdmin",
            "responses":{
               "200":{
                  "description":"Ok",
                  "content":{
                     "application/json":{
                        "schema":{
                           "type":"string"
                        }
                     }
                  }
               }
            },
            "tags":[
               "Admin"
            ],
            "security":[
               
            ],
            "parameters":[
               
            ],
            "requestBody":{
               "required":true,
               "content":{
                  "application/json":{
                     "schema":{
                        "$ref":"#/components/schemas/ApplicationUser"
                     }
                  }
               }
            }
         }
      },
      "/admin/commands/create":{
         "post":{
            "operationId":"CreateCommand",
            "responses":{
               "201":{
                  "description":"Created",
                  "content":{
                     "application/json":{
                        "schema":{
                           
                        }
                     }
                  }
               }
            },
            "tags":[
               "Admin Commands"
            ],
            "security":[
               {
                  "jwt":[
                     "admin"
                  ]
               }
            ],
            "parameters":[
               
            ],
            "requestBody":{
               "required":true,
               "content":{
                  "application/json":{
                     "schema":{
                        "$ref":"#/components/schemas/Order"
                     }
                  }
               }
            }
         }
      },
      "/admin/commands/update/{orderId}":{
         "put":{
            "operationId":"UpdateCommand",
            "responses":{
               "204":{
                  "description":"No content"
               }
            },
            "tags":[
               "Admin Commands"
            ],
            "security":[
               {
                  "jwt":[
                     "admin"
                  ]
               }
            ],
            "parameters":[
               {
                  "in":"path",
                  "name":"orderId",
                  "required":true,
                  "schema":{
                     "type":"string"
                  }
               }
            ],
            "requestBody":{
               "required":true,
               "content":{
                  "application/json":{
                     "schema":{
                        "$ref":"#/components/schemas/Order"
                     }
                  }
               }
            }
         }
      },
      "/admin/commands/delete/{orderId}":{
         "delete":{
            "operationId":"DeleteCommand",
            "responses":{
               "204":{
                  "description":"No content"
               }
            },
            "tags":[
               "Admin Commands"
            ],
            "security":[
               {
                  "jwt":[
                     "admin"
                  ]
               }
            ],
            "parameters":[
               {
                  "in":"path",
                  "name":"orderId",
                  "required":true,
                  "schema":{
                     "type":"string"
                  }
               }
            ]
         }
      },
      "/orders/execute-voice-command":{
         "post":{
            "operationId":"ExecuteCommand",
            "responses":{
               "200":{
                  "description":"Ok",
                  "content":{
                     "application/json":{
                        "schema":{
                           
                        }
                     }
                  }
               }
            },
            "tags":[
               "Orders"
            ],
            "security":[
               
            ],
            "parameters":[
               
            ]
         }
      },
      "/orders":{
         "get":{
            "operationId":"GetOrders",
            "responses":{
               "200":{
                  "description":"Ok",
                  "content":{
                     "application/json":{
                        "schema":{
                           "items":{
                              "$ref":"#/components/schemas/Order"
                           },
                           "type":"array"
                        }
                     }
                  }
               }
            },
            "tags":[
               "Orders"
            ],
            "security":[
               
            ],
            "parameters":[
               
            ]
         }
      },
      "/orders/{orderId}":{
         "get":{
            "operationId":"GetOrder",
            "responses":{
               "200":{
                  "description":"Ok",
                  "content":{
                     "application/json":{
                        "schema":{
                           "$ref":"#/components/schemas/Order"
                        }
                     }
                  }
               }
            },
            "tags":[
               "Orders"
            ],
            "security":[
               
            ],
            "parameters":[
               {
                  "in":"path",
                  "name":"orderId",
                  "required":true,
                  "schema":{
                     "type":"string"
                  }
               }
            ]
         }
      },
      "/user/register":{
         "post":{
            "operationId":"RegisterUser",
            "responses":{
               "200":{
                  "description":"Ok",
                  "content":{
                     "application/json":{
                        "schema":{
                           "type":"string"
                        }
                     }
                  }
               }
            },
            "tags":[
               "User"
            ],
            "security":[
               {
                  "jwt":[
                     "admin"
                  ]
               }
            ],
            "parameters":[
               
            ],
            "requestBody":{
               "required":true,
               "content":{
                  "application/json":{
                     "schema":{
                        "$ref":"#/components/schemas/ApplicationUser"
                     }
                  }
               }
            }
         }
      },
      "/commands/execute":{
         "post":{
            "description":"<b>Upload a command as a mono recording formatted to a wav file with 16kHz</b> <br> <b>The endpoint corresponding to the command will be executed.</b>",
            "requestBody":{
               "required":true,
               "content":{
                  "multipart/form-data":{
                     "schema":{
                        "type":"object",
                        "properties":{
                           "voiceCommand":{
                              "type":"string",
                              "format":"binary"
                           }
                        }
                     }
                  }
               }
            }
         }
      }
   },
   "servers":[
      {
         "url":"/"
      }
   ]
}

您已经定义了安全方案,但您还没有在任何地方实际使用它。在您的许多端点上,您有一个空白的 security 部分,而在其他端点上,您使用的是“jwt”,这不是您定义的“承载”方案。 (注意:您使用的是 API 密钥,而不是承载身份验证,您的名字具有误导性。)

在您希望使用此身份验证类型的端点中放置类似这样的内容。

{
   "security": [
      {
         "bearer": []
      }
   ]
}