Defining constant value in response
See original GitHub issueIn order to specify that the response for an API call is always a certain given value, I would like to create this this feature request.
If the client wants to get the details of a non-existing pet of a pet store then the server should say
{
"status": "ERROR",
"error_message": "ERROR__PET_NOT_FOUND"
}
The best way I found for describing this is to use enums with only one element, like this:
schema:
type: object
properties:
result:
type: string
enum: [ERROR]
error_code:
type: string
enum: [ERROR__PET_NOT_FOUND]
Instead of this, an exact value should be defined with an implicit type detection. So,
schema:
type: object
properties:
result:
value: "ERROR"
error_code:
value: "ERROR__PET_NOT_FOUND"
should mean the same as the previous declaration. The following scalar types should be auto-detected:
- type = string, if the value is surrounded by " symbols
- type = integer, if the value contains only digits and sign
- type = float, if the value contains digits, sign AND decimal point
Moreover, the new value
declaration should work one level above as well:
schema:
type: object
properties:
value:
result: "ERROR"
error_code: "ERROR__PET_NOT_FOUND"
This specification should mean a structure that has the two fields with these two constant values.
One more step would be the following notation:
schema:
value:
result: "ERROR"
error_code: "ERROR__PET_NOT_FOUND"
This would determine the type to be an objects and the properties as above.
This notation would be much more dense and easier to both write and understand.
Issue Analytics
- State:
- Created 6 years ago
- Reactions:63
- Comments:22 (10 by maintainers)
Top GitHub Comments
If an API had an exact response then it would seem rather redundant to call it. Why even have an API if it returns the same value every time?
Having a constant could be interesting for the Inheritance and Polymorphism case (when a
discriminator
and amapping
are defined in aoneOf
schema). Take this example from the guide:In this case,
objectType
defined in#/components/schemas/Object1
and in#/components/schemas/Object2
is just present for the discriminator mapping, it would be much nicer to have it defined as constant.