Short answer: It’s undefined behavior. Most OpenAPI serialization styles are based on RFC 6570, which provides guidance only for: primitive values, arrays of primitives, simple non-nested objects (with primitive properties). In case of other types of values (nested objects, objects containing arrays, nested arrays, arrays of objects) the behavior is undefined. Similarly, OpenAPI’s own deepObject … Read more
In your example, you can use a single model for both GET and POST/PUT, with properties only used in the GET response marked as readOnly. From the spec: readOnly Declares the property as “read only”. This means that it MAY be sent as part of a response but MUST NOT be sent as part of … Read more
To display an array example with multiple items, add the example on the array level instead of item level: cities: type: array items: type: string example: – Pune – Mumbai – Bangaluru # or # example: [Pune, Mumbai, Bangaluru] In case of array of objects, the example would look like this: type: array items: type: … Read more
This is not possible as of OpenAPI 3.1 OpenAPI 3.0/3.1 Specifications currently defines the deepObject behavior only for simple objects (with primitive properties) such as { “id”: 5, “name”: “Bob” } but not for arrays and not for nested objects. Since the behavior for arrays and nested objects is not defined, there’s really no way … Read more
type: object without properties describes a free-form object. So the response schema can be: type: object properties: original: type: object # <———- processed: type: object properties: stdFieldA: type: string stdFieldB: type: string
That’s because the two paths can be identical. I understand that the parameters may uniquely identify them, but OpenAPI 2.0 (Swagger 2.0), 3.0 and 3.1 do not support full URI templates, and the path portion alone is inspected for uniqueness. So these: /{foo} /{bar} are identical, even if foo must be a string, and bar … Read more
Given that path parameter must be required according to the OpenAPI/Swagger spec, you can consider adding 2 separate endpoints with the following paths: /get/{param1}/{param2} when param2 is provided /get/{param1}/ when param2 is not provided
You need to use the body parameter: “parameters”: [ { “in”: “body”, “name”: “body”, “description”: “Pet object that needs to be added to the store”, “required”: false, “schema”: { “$ref”: “#/definitions/Pet” } } ], and #/definitions/Pet is defined as a model: “Pet”: { “required”: [ “name”, “photoUrls” ], “properties”: { “id”: { “type”: “integer”, “format”: … Read more
It seems Swashbuckle doesn’t implement polymorphism correctly and I understand the point of view of the author about subclasses as parameters (if an action expects an Animal class and behaves differently if you call it with a dog object or a cat object, then you should have 2 different actions…) but as return types I … Read more
This is not supported as of OpenAPI 3.1, and I have to resort to a workaround. If I have a path /tags{tag_path} and I enter something like this as tag_path: /foo/bar, then the actual query request URL will be: /tags%2Ffoo%2Fbar. So, I just added support for that on my backend: the endpoint handler for /tags* … Read more