如何使用 JWT 令牌授权 Swagger jsdoc？

Question

我已经定义了我的 swagger 定义，如下所示：

const swaggerDefinition = {
  info: {
    title: 'Node Swagger API',
    version: '1.0.0',
    description: 'Describing a RESTful API with Swagger',
  },
  host: 'localhost:8000',
  basePath: '/',
  securityDefinitions: {
    JWT: {
      type: 'apiKey',
      description: 'JWT authorization of an API',
      name: 'Authorization',
      in: 'header',
    },
  },
};

但是我无法在 swagger UI 甚至 swagger.json

中获得任何授权

    info: {
       title: "Node Swagger API",
       version: "1.0.0",
       description: "Describing a RESTful API with Swagger"
    },
    host: "localhost:8000",
    basePath: "/",
    securityDefinitions: { },
    swagger: "2.0",

安全定义块在 swagger.json 文件中仍然是空的，而我已经在 server.js

中添加了 swagger 定义

任何人都可以建议如何启用授权，或者我是否在 "securitydefinitions" 中错误地使用了模式？

Answer 1

只是为了说明一件事： 安全定义定义了 api 操作的安全性，而不是文档本身。

docs 声明如下：

All security schemes used by the API must be defined in the global components/securitySchemes section. This section contains a list of named security schemes, where each scheme can be of

...

After you have defined the security schemes in the securitySchemes section, you can apply them to the whole API or individual operations by adding the security section on the root level or operation level, respectively.

... I.E 您需要全局应用该定义（如果这是您 api 的工作方式）或在安全 "tag"

下的每个操作

示例：

paths:
  /billing_info:
    get:
      summary: Gets the account billing info
      security:
        - OAuth2: [admin]   # Use OAuth with a different scope
      responses:
        '200':
          description: OK
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope
  /ping:
    get:
      summary: Checks if the server is running
      security: []   # No security
      responses:
        '200':
          description: Server is up and running
        default:
          description: Something is wrong

Answer 2

在计算 node_modules 时得到了解决方案。

只需更新到最新版本的 swagger-jsdoc。它会成功的。

Answer 3

要完成这项工作，您需要将 openapi 属性添加到您的 swaggerDefinition 对象。

从this Github issue可以看出，通过添加openapi: 3.0.1，jsdoc现在将识别安全定义。

const swaggerOptions = {
  swaggerDefinition: {
    openapi: '3.0.1', // YOU NEED THIS
    info: {
      title: 'Your API title',
      version: '1.0.0',
      description: 'Your API description'
    },
    basePath: '/',
    components: {
      securitySchemes: {
        bearerAuth: {
          type: 'http',
          scheme: 'bearer',
          bearerFormat: 'JWT',
        }
      }
    },
    security: [{
      bearerAuth: []
    }]
  },
  apis: ['/some/path.js|yml'],
};

如果您不需要全局安全定义，则需要从您的 swaggerDefinition

中删除 以下内容

security: [{
  bearerAuth: []
}]

您现在可以将其添加到个人 API 请求中：

/**
 * @swagger
 * /users:
 *  get:
 *    security:              # <--- ADD THIS
 *      - bearerAuth: []     # <--- ADD THIS
 *    tags:
 *      - Users
 *    description: Returns a single person based on their JWT token
 *    produces:
 *      - application/json
 *    responses:
 *      200:
 *        description: A single person
 *        schema:
 *            $ref: '#/definitions/PersonSimple'
 */
router.get('/users', passport.authenticate('jwt', {session: false}), (req, res, next) => {

    /**
    * Just using the `passport-jwt` middleware as an example here.
    * If the JWT is valid, it attaches the user from the database
    * to the request object
    */
    res.status(200).json({ success: true, user: req.user });
});

如何使用 JWT 令牌授权 Swagger jsdoc？

How to authorise Swagger jsdoc with JWT token?

node.js

jwt

swagger

swagger-ui

swagger-2.0