请求中的 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": []
}
]
}
我使用 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": []
}
]
}