如何在 Swagger 3.0 中为组件编写嵌套对象

Posted 2023-02-19

【中文标题】如何在 Swagger 3.0 中为组件编写嵌套对象

【英文标题】：How to write a nested object in Swagger 3.0 for components

【发布时间】：2022-01-07 17:10:06

【问题描述】：

所以我正在开发数据传输对象文件中的组件 yaml 文件，以便我可以引用它们。

这是我目前所拥有的：

/**
* @openapi
* components:
*   schemas:
*     VerifiedEmailAddressDto:
*       type: object
*       required:
*         - email
*       properties:
*         _type:
*           type: string
*         email:
*           type: string
*           description: a users email.
*         reset:
*           type: boolean
*         passwordRules:
*           type: object
*           properties:
*             minLength:
*               type: number
*             maxLength:
*               type: number
*             minRequiredUppercase:
*               type: number
*       example:
*         _type: VerifiedEmailAddressDto
*         email: [e-mail]
*         reset: false
*         passwordRules:
*/
export class VerifiedEmailAddressDto 
  readonly _type = "VerifiedEmailAddressDto";
  readonly email: string;
  readonly reset: boolean;
  readonly passwordRules:  minLength: number; maxLength: number; minRequiredUppercase: number; minRequiredLowerCase: number; minRequiredSymbols: number ;

  constructor(email: string, reset: boolean, passwordRules:  minLength: number; maxLength: number; minRequiredUppercase: number; minRequiredLowerCase: number; minRequiredSymbols: number ) 
   this.email = email;
   this.reset = reset;
   this.passwordRules = passwordRules;
  

passwordRules 的最后一个属性是该对象内的一个对象。所以它是一个嵌套对象，但到目前为止我所拥有的并没有给我这个：

 "_type": "VerifiedEmailAddressDto",
 "email": "[e-mail]",
 "reset": false,
 "passwordRules": 
   "minLength": 8,
   "maxLength": 25,
   "minRequiredUppercase": 1,
   "minRequiredLowerCase": 1,
   "minRequiredSymbols": 0
  

但老实说我不确定如何完成这个，我假设这部分：

*         passwordRules:
*           type: object
*           properties:
*             minLength:
*               type: number
*             maxLength:
*               type: number
*             minRequiredUppercase:
*               type: number

是正确的，但在示例中提供的是我坚持的内容，在这种情况下，甚至上述内容可能也不正确。

这个想法是为了让我最终可以在这里引用它：

/**
* @openapi
* /api/v2/auth/check_mail:
*   post:
*     tags: [Auth]
*     description: This endpoint checks to see if an email is unique or is in use.
*     requestBody:
*       required: true
*       content:
*         application/json:
*           schema:
*           type: object
*           $ref: '#/components/schemas/VerifiedEmailAddressDto'
*     responses:
*       201:
*         description: Get permissions.
*         content:
*           application/json:
*             schema:
*             $ref: '#/components/schemas/VerifiedEmailAddressDto'
*/
this.app.post(p().api.v2.auth.check_email.$url, [
// TODO restrict number of queries by IP by period of time.
authMiddleware.validateEmailQuery,
credentialsController.verifyEmailAddress
]);

所以我可以像这样为passwordRules 显示一个空对象：

/**
* @openapi
* components:
*   schemas:
*     VerifiedEmailAddressDto:
*       type: object
*       required:
*         - email
*       properties:
*         _type:
*           type: string
*         email:
*           type: string
*           description: a users email.
*         reset:
*           type: boolean
*         passwordRules:
*           type: object
*           properties:
*             minLength:
*               type: number
*             maxLength:
*               type: number
*             minRequiredUppercase:
*               type: number
*       example:
*         _type: VerifiedEmailAddressDto
*         email: [e-mail]
*         reset: false
*         passwordRules: 
*/
export class VerifiedEmailAddressDto 
  readonly _type = "VerifiedEmailAddressDto";
  readonly email: string;
  readonly reset: boolean;
  readonly passwordRules:  minLength: number; maxLength: number; minRequiredUppercase: number; minRequiredLowerCase: number; minRequiredSymbols: number ;

  constructor(email: string, reset: boolean, passwordRules:  minLength: number; maxLength: number; minRequiredUppercase: number; minRequiredLowerCase: number; minRequiredSymbols: number ) 
   this.email = email;
   this.reset = reset;
   this.passwordRules = passwordRules;
  

但是如果我尝试像这样在对象中添加它的属性：

passwordRules: 
  minLength: 8
  maxLength: 25

如果我试着把例子放在这样的地方，我什么也得不到：

  *         passwordRules:
    *           type: object
    *           properties:
    *             minLength:
    *               type: number
    *               example: 8
    *             maxLength:
    *               type: number
    *               example: 25
    *             minRequiredUppercase:
    *               type: number
    *               example: 1
    *       example:
    *         _type: VerifiedEmailAddressDto
    *         email: [e-mail]
    *         reset: false
    *         passwordRules: 

我还是一无所获。

【问题讨论】：

您在为passwordRules 在components.schemas.VerifiedEmailAddressDto.example 下编写示例而苦苦挣扎，我理解了吗？

是的，passwordRules 是或应该是一个对象，我在上面举了一个它应该是什么样子的例子，但无论我尝试了什么，它总是会中断。

你说That last property of passwordRules is an object inside this object.这个属性在哪里？它在您的代码 sn-ps 中不可见。

@gaitat，属性passwordRules在第一、二、三码sn-ps中。

【参考方案1】：

在 OpenAPI 中，可以像 root example object 一样指定示例嵌套对象。例如，作为 YAML 键值对。

所以下面的example 规范：

...
*         passwordRules:
*           type: object
*           properties:
*             minLength:
*               type: number
*             maxLength:
*               type: number
*             minRequiredUppercase:
*               type: number
*             minRequiredLowerCase:
*               type: number
*             minRequiredSymbols:
*               type: number
*       example:
*         _type: VerifiedEmailAddressDto
*         email: [e-mail]
*         reset: false
*         passwordRules:
*           minLength: 8
*           maxLength: 25
*           minRequiredUppercase: 1
*           minRequiredLowerCase: 1
*           minRequiredSymbols: 0
...

..在 Swagger-UI 中看起来像这样：