cookbook for how to test for various unintuitive scenarios

[karenetheridge]

e.g.

• request body requiredness can be specified directly with required: true.

• to indicate that a request body is NOT included, specify a Content-Length header that is required=false, with schema type: integer, const: 0. This will result in no error if the header is missing, and an error if the header is present and its value is anything but 0. You can also specify a requestBody with media-type */* and schema false which will produce a failure if there is a non-zero-length body, just in case the Content-Length header lies.

• to indicate that a response body is mandatory, specify that the Content-Length header is required=true, with schema type: integer, minimum: 1. this can be abstracted as /components/headers/require_body_payload.

• to indicate that a response body is NOT included, follow the recipe for request bodies above.

• to test a header value, of which there can only be one: use schema type: string type: array maxItems: 1

• to test a header value, of which there may be one or more than one: use schema type: array and test each item with items, maxItems, minItems. explode must be false

• to test a single header value as a number: use schema type: number

• to test a header value, of which there may be one or more than one, as numbers: use schema type: array; items: { type: number }.

(some of these not implemented yet, see #8, #14)

[karenetheridge]

• how do I indicate that a query parameter can be used more than once, and how do I list the possible keys/values for this parameter. (answer - with a combination of style/explode, type: object, propertyNames: { enum: [ ... ] })
  see fastly/api-documentation's x-enum-multiple)

[karenetheridge]

when using a $ref to a model (e.g. for defining common endpoints for a specific resource), how do I mark some fields as not permitted in certain endpoints and not others:

method 1: reference the model, to get the type checking, and then only explicitly allow properties you list (additionalProperties: false will prevent the others).

type: object
additionalProperties: false
$ref: '#/components/schemas/model.foo'
properties:
  name: true
  blah: true

method 2: reference the model, to get the type checking, and then explicitly block the properties you want to disallow:

type: object
$ref: '#/components/schemas/model.foo'
properties:
  id: false
  created_at: false
  updated_at: false
  deleted_at: false

method 1 is safer because you need to explicitly allow new properties when you add properties to the model, whereas in method 2 you need to remember to block new properties that shouldn't be included. However, sometimes the blocklist is going to be much shorter (e.g. just a primary key and timestamps), and you might even find it useful to put that into a $ref for reuse.

[karenetheridge]

check that a header or query parameter is NOT present:

parameters:
- name: Foo
  in: header
  required: false
  schema: false

and in 0.048, this should also work for headers:

parameters:
- name: Foo
  in: header
  required: false
  schema:
    type: 'null'