如何在 nodejs 的 Swagger UI(swagger.json) 中的 header 中表示自定义令牌

Question

我正在用 ExpressJs 创建一个 Restful 服务器。我已经集成了 swagger-jsdoc。以下是相关文件。下面（header.png）是我希望我的 header 看起来像招摇的 UI。但是，当我打开 swagger UI (http://localhost:3000/api-docs/) 时，我无法在 header 中看到令牌标签（令牌和身份验证）。

swagger.json

{
    "swagger": "2.0",
    "info": {
        "version": "1.0.0",
        "title": "Viswa API"
    },
    "host": "localhost:3000",
    "basePath": "/api",
    "tags": [{
        "name": "Customers",
        "description": "API for customers in the system"
    }],
    "schemes": [
        "http"
    ],
    "consumes": [
        "application/json"
    ],
    "produces": [
        "application/json"
    ],
    "securityDefinitions": {
        "Bearer": {
            "type": "apiKey",
            "name": "Authorization",
            "in": "header"
        },
        "JWT": {
            "type": "apiKey",
            "name": "token",
            "in": "header"
        }
    },
    "paths": {
        "/customer": {
            "post": {
                "tags": [
                    "Customers"
                ],
                "description": "Create new customer in system",
                "parameters": [{
                    "name": "customer",
                    "in": "body",
                    "description": "Customer that we want to create",
                    "schema": {
                        "$ref": "#/definitions/Customer"
                    }
                }],
                "produces": [
                    "application/json"
                ],
                "responses": {
                    "201": {
                        "description": "New customer is created",
                        "schema": {
                            "$ref": "#/definitions/Customer"
                        }
                    }
                }
            }
        }
    },
    "definitions": {
        "Customer": {
            "required": [
                "email"
            ],
            "properties": {
                "customer_name": {
                    "type": "string"
                },
                "customer_email": {
                    "type": "string"
                }
            }
        }
    }
}

app.route

var apiRoutes = express.Router();
app.use('/api', apiRoutes);
// swagger definition
var swaggerUi = require('swagger-ui-express'),
swaggerDocument = require('../swagger.json');

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));
app.use('/api/v1', apiRoutes);

当前的 Swagger UI:

Answer 1

您缺少安全标签。您可以在 securityDefinitions 标记下方全局定义它，也可以为每个 API 端点定义一个。

看看 问题。

Answer 2

您可以添加安全标签

"security": [ { "Bearer": [] } ], 

将其添加到您的路径部分后

"paths": {
        "/customer": {
            "post": {
                "security": [ { "Bearer": [] } ],
                "tags": [
                    "Customers"
                ],
                "description": "Create new customer in system",
                "parameters": [{
                    "name": "customer",
                    "in": "body",
                    "description": "Customer that we want to create",
                    "schema": {
                        "$ref": "#/definitions/Customer"
                    }
                }],
                "produces": [
                    "application/json"
                ],
                "responses": {
                    "201": {
                        "description": "New customer is created",
                        "schema": {
                            "$ref": "#/definitions/Customer"
                        }
                    }
                }
            }
        }
    },

Answer 3

您可以在路径定义中定义header参数。像这样

 "paths": {
    "/customer": {
                parameters: [{ name: "Authorization", in: "header", type: "string", description: "auth token" }]

                }
        }