Swagger 招摇过市：通用响应/有效负载对象，但每个API定义的数据不同？

表示具有消息、总元素、数据和状态等基本字段的通用响应/有效负载对象的最佳方式是什么？其中，每个API之间的可变性是数据元素。例如，一个API可以用于权限，因此数据元素将保存一个权限数组。但对于另一个API，它将包含不同的对象类型数组。我的主要目标是对有效负载对象进行重用，并定义实际数据的下一个“层”

我希望能够定义一种通用的数据类型，比如具有基本字段的“响应”，但我希望能够为每个API进一步定义该内容（包含权限或角色或其他内容的数据）

下面是一些JSON示例，介绍了我们尝试过的内容，但没有按照我们在Swagger UI中所期望的方式呈现（即，一个由4个元素组成的平面结构，其中数据是根据API定义的）

示例1-组成：

    {
    "swagger": "2.0",
    "host": "localhost:8888",
    "info": {
        "version": "0.0.1",
        "title": "API"
    },
    "paths": {
        "/permissions": {
            "get": {
                "description": "Returns all permissions",
                "operationId": "getPermissions",
                "produces": [
                    "application/json"
                ],
                "responses": {
                    "200": {
                        "description": "success",
                        "schema": {
                            "$ref": "#/definitions/permissionResponse"
                        }
                    }
                }
            }
        }
    },
    "definitions": {
        "response": {
            "type": "object",
            "properties": {
                "message": {
                    "type": "string",
                    "description": "A string indicating the response from the server."
                },
                "totalElements": {
                    "type": "integer",
                    "format": "int64",
                    "description": "The number of items retrieved."
                },
                "status": {
                    "type": "string",
                    "description": "A string indicating the response from the server."
                }
            }
        },
        "permissionResponse": {
            "allOf": [
                {
                    "$ref": "#/definitions/response"
                }, {
                    "type": "object",
                    "properties": {
                        "data": {
                            "type": "array",
                            "description": "The collection of items returned from the API request.",
                            "items": {
                                "$ref": "#/definitions/permission"
                            }
                        }
                    }
                }
            ]
        },
        "permission": {
            "type": "object",
            "properties": {
                "id": {
                    "type": "integer",
                    "format": "int64",
                    "description": "Unique identifier representing a specific permission."
                },
                "label": {
                    "type": "string",
                    "description": "The label of a permission."
                },
                "description": {
                    "type": "string",
                    "description": "A description of the permission."
                },
                "active": {
                    "type": "boolean",
                    "description": "A flag indicating whether a permission is active."
                }
            },
            "required": [
                "id",
                "label",
                "description",
                "active"
            ]
        }
    }
}

示例2-成分变化：

    {
    "swagger": "2.0",
    "host": "localhost:8888",
    "info": {
        "version": "0.0.1",
        "title": "API"
    },
    "paths": {
        "/permissions": {
            "get": {
                "description": "Returns all permissions",
                "operationId": "getPermissions",
                "produces": [
                    "application/json"
                ],
                "responses": {
                    "200": {
                        "description": "success",
                        "schema": {
                            "$ref": "#/definitions/permissionResponse"
                        }
                    }
                }
            }
        }
    },
    "definitions": {
        "response": {
            "type": "object",
            "properties": {
                "message": {
                    "type": "string",
                    "description": "A string indicating the response from the server."
                },
                "totalElements": {
                    "type": "integer",
                    "format": "int64",
                    "description": "The number of items retrieved."
                },
                "status": {
                    "type": "string",
                    "description": "A string indicating the response from the server."
                }
            }
        },
        "permissionResponse": {
            "allOf": [
                {
                    "$ref": "#/definitions/response"
                }],
            "type": "object",
            "properties": {
                "data": {
                    "type": "array",
                    "description": "The collection of items returned from the API request.",
                    "items": {
                        "$ref": "#/definitions/permission"
                    }
                }
            }
        },
        "permission": {
            "type": "object",
            "properties": {
                "id": {
                    "type": "integer",
                    "format": "int64",
                    "description": "Unique identifier representing a specific permission."
                },
                "label": {
                    "type": "string",
                    "description": "The label of a permission."
                },
                "description": {
                    "type": "string",
                    "description": "A description of the permission."
                },
                "active": {
                    "type": "boolean",
                    "description": "A flag indicating whether a permission is active."
                }
            },
            "required": [
                "id",
                "label",
                "description",
                "active"
            ]
        }
    }

示例3-其他属性：

    {
    "swagger": "2.0",
    "host": "localhost:8888",
    "info": {
        "version": "0.0.1",
        "title": "API"
    },
    "paths": {
        "/permissions": {
            "get": {
                "description": "Returns all permissions",
                "operationId": "getPermissions",
                "produces": [
                    "application/json"
                ],
                "responses": {
                    "200": {
                        "description": "success",
                        "schema": {
                            "$ref": "#/definitions/permissionResponse"
                        }
                    }
                }
            }
        }
    },
    "definitions": {
        "response": {
            "type": "object",
            "properties": {
                "message": {
                    "type": "string",
                    "description": "A string indicating the response from the server."
                },
                "totalElements": {
                    "type": "integer",
                    "format": "int64",
                    "description": "The number of items retrieved."
                },
                "status": {
                    "type": "string",
                    "description": "A string indicating the response from the server."
                }
            }
        },
        "permissionResponse": {
            "type": "object",
            "properties": {
                "data": {
                    "type": "array",
                    "description": "The collection of items returned from the API request.",
                    "items": {
                        "$ref": "#/definitions/permission"
                    }
                }
            },
            "additionalProperties": {
                "$ref": "#/definitions/response"
            }
        },
        "permission": {
            "type": "object",
            "properties": {
                "id": {
                    "type": "integer",
                    "format": "int64",
                    "description": "Unique identifier representing a specific permission."
                },
                "label": {
                    "type": "string",
                    "description": "The label of a permission."
                },
                "description": {
                    "type": "string",
                    "description": "A description of the permission."
                },
                "active": {
                    "type": "boolean",
                    "description": "A flag indicating whether a permission is active."
                }
            },
            "required": [
                "id",
                "label",
                "description",
                "active"
            ]
        }
    }

示例1使用swagger2markup很好地呈现，它显示了数据与其他3个元素的合并视图，并具有权限数组。但是，对于Swagger UI，它会以不同的方式渲染，将对象分离出来。 呈现的标记：

大摇大摆的用户界面

呈现的招摇过市UI-已展开