The possibility to mark schemas and schema properties as deprecated was added in OpenAPI 3.0: openapi: 3.0.1 … components: schemas: Service: type: object properties: location: type: string description: Location of the service example: ‘400 Street name, City State postcode, Country’ deprecated: true # <——— If you use OpenAPI 2.0 (Swagger 2.0), the only thing you … Read more
OpenAPI 2.0 OAS2 does not support multiple response schemas per status code. You can only have a single schema, for example, a free-form object (type: object without properties). OpenAPI 3.x In OAS3 you can use oneOf to define multiple possible request bodies or response bodies for the same operation: openapi: 3.0.0 … paths: /path: get: … 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
OpenAPI Specification 2.0 In Swagger 2.0 (OpenAPI Specification 2.0), use a form parameter (in: formData) with the type set to file. Additionally, the operation’s consumes must be multipart/form-data. consumes: – multipart/form-data parameters: – name: file in: formData # <—– description: The uploaded file data required: true type: file # <—– OpenAPI Specification 3.0 In OpenAPI … Read more
“enum” works like this in OpenAPI 2.0: { “in”: “query”, “name”: “sample”, “description”: “a sample parameter with an enum value”, “type”: “string”, “enum”: [ “1”, “2”], “required”: true } and in OpenAPI 3.0: { “in”: “query”, “name”: “sample”, “description”: “a sample parameter with an enum value”, “schema”: { “type”: “string”, “enum”: [ “1”, “2”] }, … Read more
By default, fields in a model are optional unless you put them in the required list. Below is an example – id, category are optional fields, name is required. Note that required is not an attribute of fields, but an attribute of the object itself – it’s a list of required properties. type: object required: … Read more
There’s no built-in type for UUID, but the OpenAPI Specification suggests using type: string format: uuid From the Data Types section (emphasis mine): Primitives have an optional modifier property: format. OAS uses several known formats to define in fine detail the data type being used. However, to support documentation needs, the format property is an … Read more
An easy way to create simple mock from an OpenAPI (fka Swagger) spec without code is to use a tool call prism available at http://github.com/stoplightio/prism written in Typescript. This command line is all you need: ./prism run –mock –list –spec <your swagger spec file> The mock server will return a dynamic response based on the … 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
The OpenAPI Specification says that you must use: type: string format: date # or date-time The patterns supported are defined in RFC 3339, section 5.6 (effectively ISO 8601) and examples are provided in section 5.8. So for date values should look like “2018-03-20” and for date-time, “2018-03-20T09:12:28Z”. As such, when using date or date-time, the … Read more