Trong API "đơn giản hóa" của tôi, tất cả các phản hồi đều có nguồn gốc ( kế thừa ) từ một lớp "phản hồi" cơ sở. Lớp phản hồi bao gồm phần đầu chứa siêu dữ liệu và phần thân chứa dữ liệu cốt lõi mà người dùng đang yêu cầu. Phản hồi (trong JSON) được bố trí sao cho tất cả siêu dữ liệu đều nằm trên "lớp" đầu tiên và phần thân là một thuộc tính duy nhất được gọi là "body" như vậy
response
|--metadata attribute 1 (string/int/object)
|--metadata attribute 2 (string/int/object)
|--body (object)
|--body attribute 1 (string/int/object)
|--body attribute 2 (string/int/object)
Tôi đã cố gắng xác định mối quan hệ này một cách vênh váo với JSON sau:
{
...
"definitions": {
"response": {
"allOf": [
{
"$ref": "#/definitions/response_header"
},
{
"properties": {
"body": {
"description": "The body of the response (not metadata)",
"schema": {
"$ref": "#/definitions/response_body"
}
}
}
}
]
},
"response_header": {
"type": "object",
"required": [
"result"
],
"properties": {
"result": {
"type": "string",
"description": "value of 'success', for a successful response, or 'error' if there is an error",
"enum": [
"error",
"success"
]
},
"message": {
"type": "string",
"description": "A suitable error message if something went wrong."
}
}
},
"response_body": {
"type": "object"
}
}
}
Sau đó, tôi cố gắng tạo các phản hồi khác nhau bằng cách tạo các lớp body / header khác nhau kế thừa từ body / header, rồi tạo các lớp phản hồi con bao gồm các lớp header / body có liên quan (được hiển thị trong mã nguồn ở dưới cùng). Tuy nhiên, tôi chắc chắn rằng đây là cách làm sai hoặc cách triển khai của tôi không chính xác. Tôi đã không thể tìm thấy một ví dụ về kế thừa trong đặc tả swagger 2.0 (được hiển thị bên dưới) nhưng đã tìm thấy một ví dụ về thành phần .
Tôi khá chắc chắn rằng "kẻ phân biệt đối xử" này có một phần lớn để chơi, nhưng không chắc tôi cần phải làm gì.
Câu hỏi
Ai đó có thể chỉ cho tôi cách người ta phải triển khai thành phần + kế thừa trong swagger 2.0 (JSON), tốt hơn là bằng cách "sửa chữa" mã ví dụ của tôi bên dưới. Cũng sẽ rất tuyệt nếu tôi có thể chỉ định một lớp ErrorResponse kế thừa từ phản hồi trong đó thuộc tính "result" trong tiêu đề luôn được đặt thành "error".
{
"swagger": "2.0",
"info": {
"title": "Test API",
"description": "Request data from the system.",
"version": "1.0.0"
},
"host": "xxx.xxx.com",
"schemes": [
"https"
],
"basePath": "/",
"produces": [
"application/json"
],
"paths": {
"/request_filename": {
"post": {
"summary": "Request Filename",
"description": "Generates an appropriate filename for a given data request.",
"responses": {
"200": {
"description": "A JSON response with the generated filename",
"schema": {
"$ref": "#/definitions/filename_response"
}
}
}
}
}
},
"definitions": {
"response": {
"allOf": [
{
"$ref": "#/definitions/response_header"
},
{
"properties": {
"body": {
"description": "The body of the response (not metadata)",
"schema": {
"$ref": "#/definitions/response_body"
}
}
}
}
]
},
"response_header": {
"type": "object",
"required": [
"result"
],
"properties": {
"result": {
"type": "string",
"description": "value of 'success', for a successful response, or 'error' if there is an error",
"enum": [
"error",
"success"
]
},
"message": {
"type": "string",
"description": "A suitable error message if something went wrong."
}
}
},
"response_body": {
"type": "object"
},
"filename_response": {
"extends": "response",
"allOf": [
{
"$ref": "#definitions/response_header"
},
{
"properties": {
"body": {
"schema": {
"$ref": "#definitions/filename_response_body"
}
}
}
}
]
},
"filename_response_body": {
"extends": "#/definitions/response_body",
"properties": {
"filename": {
"type": "string",
"description": "The automatically generated filename"
}
}
}
}
}
Cập nhật sơ đồ
Để thử và làm rõ những gì tôi muốn, tôi đã tạo sơ đồ rất cơ bản dưới đây nhằm mục đích chỉ ra rằng tất cả các phản hồi đều là các bản khởi tạo của đối tượng "response" đã được tạo bởi (thành phần) bằng cách sử dụng bất kỳ sự kết hợp nào của các đối tượng response_header và response_body. Các đối tượng response_header và response_body có thể được mở rộng và chèn vào bất kỳ đối tượng phản hồi nào, điều này được thực hiện trong trường hợp tệpname_response sử dụng con tệp tên_response_body của lớp response_body cơ sở. Cả phản hồi lỗi và phản hồi thành công đều sử dụng đối tượng "phản hồi".
