咨询：创建返回嵌套JSON的OAS3 200响应的语法及双引用可行性

嘿，我来帮你搞定OpenAPI 3里嵌套JSON响应的定义问题！其实完全不需要什么双引号的特殊操作——OAS3本身就原生支持层级化的schema定义，只要用object类型嵌套就能轻松实现你要的结构。

先给你举个实际的例子：假设你要返回的嵌套JSON是这样的：

{
  "id": 123,
  "user_info": {
    "username": "john_doe",
    "email": "john@example.com",
    "profile": {
      "age": 30,
      "location": "New York"
    }
  },
  "metadata": {
    "created_at": "2024-05-20T10:00:00Z",
    "updated_at": "2024-05-20T14:30:00Z"
  }
}

对应的OAS3 200响应可以有两种写法，看你需求选：

1. 内联定义（适合简单结构） #

直接在响应里嵌套object和properties，一目了然：

openapi: 3.0.3
info:
  title: Nested JSON Response Demo
  version: 1.0.0
paths:
  /users/{userId}:
    get:
      summary: Fetch a user with nested details
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Success - returns nested user data
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  user_info:
                    # 第一层嵌套对象
                    type: object
                    properties:
                      username:
                        type: string
                      email:
                        type: string
                        format: email
                      profile:
                        # 第二层嵌套对象
                        type: object
                        properties:
                          age:
                            type: integer
                          location:
                            type: string
                  metadata:
                    # 另一个独立的嵌套对象
                    type: object
                    properties:
                      created_at:
                        type: string
                        format: date-time
                      updated_at:
                        type: string
                        format: date-time
                # 标记必填字段
                required: [id, user_info]

2. 复用Schema（适合复杂/重复使用的结构） #

如果嵌套层级多或者某些结构要在多个地方复用，把它们抽成单独的Schema放到components里会更清晰：

components:
  schemas:
    UserProfile:
      type: object
      properties:
        age:
          type: integer
        location:
          type: string
    UserInfo:
      type: object
      properties:
        username:
          type: string
        email:
          type: string
          format: email
        profile:
          # 引用刚才定义的Profile Schema
          $ref: '#/components/schemas/UserProfile'
      required: [username, email]
    Metadata:
      type: object
      properties:
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    UserResponse:
      type: object
      properties:
        id:
          type: integer
        user_info:
          $ref: '#/components/schemas/UserInfo'
        metadata:
          $ref: '#/components/schemas/Metadata'
      required: [id, user_info]

然后在响应里直接引用这个主Schema就行：

responses:
  '200':
    description: Success - returns nested user data
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/UserResponse'

关于你之前试的双引号 #

其实你不需要用双引号来处理嵌套结构——双引号只是用来包裹YAML/JSON里的字符串值，和层级结构定义完全没关系。只要确保每个嵌套的层级都用type: object声明，然后在properties里定义下一层的字段就可以了，不管多少层嵌套都适用。

内容的提问来源于stack exchange，提问作者Maarduk