How to describe a single response format for all the REST API in the Swagger OpenAPI3?

There are many controllers, all of them give the answer in the same format:
{
 "response": true, # true/false
 "error": {
 "code": 0, # 0 or error code
 "message": "" # the error text
},
 "data": null, # null or the response data
}


All forms of requests, responses, headers, etc. made in the components, and connect to $ref

But it is impossible to combine a common answer format with the response data. Here's an example:
paths:
/system/banner/{position}:
get:
 # ...
parameters:
 - name: position
 # ...
responses:
200:
 description: OK
headers:
 # ...
content:
application/json:
schema:
allOf:
 - $ref: '#/components/responses/CommonResponse' # <-- Single response format
 - properties: <-- # It needs to be supplemented with data
data:
 $ref: '#/components/schemas/BannerList'
400:
 # ...

As a result, the svagger generates this:
{
 "data": [
{
 "id": 0,
 "title": "string",
 "content": "string",
 "date_created": "2019-08-07T10:54:38.215 Z",
 "date_edited": "2019-08-07T10:54:38.215 Z"
}
]
}

and it's like this:
{
 "response": true,
 "error": {
 "code": 0,
 "message": ""
},
 "data": [
{
 "id": 0,
 "title": "string",
 "content": "string",
 "date_created": "2019-08-07T10:54:38.215 Z",
 "date_edited": "2019-08-07T10:54:38.215 Z"
}
]
}


What am I doing wrong?
March 25th 20 at 13:47
2 answers
March 25th 20 at 13:49
Solution
properties must be on the same level as allOf, like so:
allOf:
 - $ref: '#/components/responses/CommonResponse' # <-- Single response format
properties: <-- # It needs to be supplemented with data
data:
 $ref: '#/components/schemas/BannerList'
Alas, not working. Parsed without errors, but the result is the same as me. - Geo.Schroeder13 commented on March 25th 20 at 13:52
@Geo.Schroeder13, strange, works for me, try a scheme to make a separate object - johann_Kunze98 commented on March 25th 20 at 13:55
@johann_Kunze98, I found the cause. I have one object in the responses, and the second schemas. And they don't Marjatta
If you move CommonResponse with responses in schemas, it begins to work.
content:
application/json:
schema:
allOf:
 - $ref: '#/components/schemas/CommonResponse'
 - properties:
data:
 $ref: '#/components/schemas/BannerList'

Thank you! I note the decision of the - Geo.Schroeder13 commented on March 25th 20 at 13:58
March 25th 20 at 13:51
Handles. You know that this is not the REST, right?
It doesn't matter. The need to reduce the description in the Svagger, to combine the two circuits - General and specific data - Geo.Schroeder13 commented on March 25th 20 at 13:54
@Geo.Schroeder13, it is possible to do nested relations, but not Vice versa, so that will not work. But don't call it REST, please, for tahlia and with the experience of 9 years should be ashamed - esta_Casp commented on March 25th 20 at 13:57
Handles

Seriously?
You know that this is not the REST, right?

If you don't know something, you can just keep quiet, clever words won't save you. - chauncey.Mills commented on March 25th 20 at 14:00
@chauncey.Mills, if you know how to do the example in the Studio) well, please, the arguments for what is REST. - esta_Casp commented on March 25th 20 at 14:03
@esta_Casp, chomu not rest then? A basic set of principles Resta respected like. - johann_Kunze98 commented on March 25th 20 at 14:06
Let's not get REST, OK? Let it be just an API. The crux of the matter will not change.

Need to reduce the number of manual work in the description of the API. To describe each answer with your hands is not an option, I still hope that I something not so made and data General format of the response how it is possible to Margit. - Geo.Schroeder13 commented on March 25th 20 at 14:09
@Geo.Schroeder13, the maximum that can offer every top - level key described as a separate model and link. thus it is possible to simplify, but this is the maximum - esta_Casp commented on March 25th 20 at 14:12
@johann_Kunze98, so that in a HTTP REST view should contain only the object, but everything else should be in the meta information: that is, in the body of the response only the state of the object, and everything else in the http headers. in addition errors may exist only in the form of a 2xx response if not response. part of the response: bool in General, hints at the duality - esta_Casp commented on March 25th 20 at 14:15
@esta_Casp, these errors are duplicated in the response body for specific reasons: not all clients can work normally with non 200 statuses answers. Because we have the data duplicated and modes may change. By default, the HTTP codes: 200 - OK, and if error, 400, 401, 403, etc. according to the situation. - Geo.Schroeder13 commented on March 25th 20 at 14:18
@Geo.Schroeder13, I mean not all customers? people or robots?) if people then I can only sympathize with, but robots can - esta_Casp commented on March 25th 20 at 14:21
@esta_Casp, there were occasions when the developers of the API client that always asked to give two hundred, and the error code and message to return in the response body. This was with JS, and mobile applications(Java, not sure). If JS is still clear - the question of qualification, with mobile developers is quite clear why: the old library or framework? Don't ask, don't know. - Geo.Schroeder13 commented on March 25th 20 at 14:24
@Geo.Schroeder13, it is always low-skilled. But if there below, David said, which can help, but for me it is if it works the savagery and not readability - esta_Casp commented on March 25th 20 at 14:27
@esta_Casp, thank you! - Geo.Schroeder13 commented on March 25th 20 at 14:30

Find more questions by tags RESTful APIJSON