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
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
Swagger Editor Paste your OpenAPI 2.0 definition into https://editor.swagger.io and select Edit > Convert to OpenAPI 3 from the menu. Swagger Converter Converts OpenAPI 2.0 and Swagger 1.x definitions to OpenAPI 3.0. https://converter.swagger.io/api/convert?url=OAS2_YAML_OR_JSON_URL This gives you JSON. If you want YAML, send the request with the Accept: application/yaml header: curl “https://converter.swagger.io/api/convert?url=OAS2_YAML_OR_JSON_URL” -H “Accept: application/yaml” -o … Read more
This feature already exists in Swagger 2.0. The linked ticket talks about some specific mechanics of it which doesn’t affect the functionality of this feature. At the top level object (referred to as the Swagger Object), there’s a parameters property where you can define reusable parameters. You can give the parameter any name, and refer … Read more
I don’t think you can use “object” as query parameter in Swagger spec as query parameter only supports primitive type (https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#data-types)
Yes, you can have a path item that references another path item: paths: /ab: post: summary: … … responses: … /a-b: $ref: ‘#/paths/~1ab’ # <———— Here, ~1ab is an encoded version of /ab (see below). One limitation of this approach is that you cannot have operationId in all operations of the referenced path item. This … Read more