A query parameter containing a comma-separated list of values is defined as an array. If the values are predefined, then it’s an array of enum. By default, an array may have any number of items, which matches your “none or more” requirement. If needed, you can restrict the number of items using minItems and maxItems, … Read more
Like in JSON Schema, OpenAPI schema objects do not require a type, and you are correct in that no type means any type. “Type-specific” keywords such as properties, items, minLength, etc. do not enforce a type on the schema. It works the other way around – when an instance is validated against a schema, these … Read more
It depends on what kind of parameters they are. The examples below are in YAML (for readability), but you can use http://www.json2yaml.com to convert them to JSON. Security-related parameters: Authorization header, API keys, etc. Parameters used for authentication and authorization, such as the Authorization header, API key, pair of API keys, etc. should be defined … Read more
Indeed, the example you give here is invalid because $ref can’t co-exist with other properties in the same object. $ref is a JSON Reference, and by definition, will cause the other properties to be ignored. From your question, I assume you’re looking for basic composition (rather than inheritance). This is achievable using the allOf keyword. … Read more
OpenAPI 2.0 (fka Swagger 2.0) Looks like I can add the following global response definition: # An object to hold responses that can be used across operations. # This property does not define global responses for all operations. responses: NotAuthorized: description: The requester is unauthorized. schema: $ref: ‘#/definitions/Error’ However I will still need to reference … Read more
Your example is correct. how do I document what the restrictions are for the “key” in the object? Ideally I’d like to say something like “it’s not just any arbitrary string, it’s the ID that corresponds to the child”. Is this supported in any way? OpenAPI 3.1 OAS 3.1 fully supports JSON Schema 2020-12, including … 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
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
You can’t describe query parameters as part of the path in Swagger. You have to declare those explicitly as query parameters. “/v1/products”:{ “get”:{ “tags”:[ “Search Text” ], “summary”:”Get Products by searching text, countrycode, page number, pagesize, project and country(optional)”, “description”:”Get Products by searching text, countrycode, page number, pagesize, project and country(optional)”, “operationId”:”getProductName”, “produces”:[ “application/json”, “application/xml” … 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