Add default responses

Currently, every single operation must declare its’ own responses. This causes a whole bunch of duplication, which would be better served by having a top-level responses section in the spec. Like the security construct, operations could override the default responses on their own.

[michael-o]

A simple usecase, status code which apply to all paths: 401, 403, 500, 502, 503, 504. They – in most cases – don’t require any response body. Maybe 500.

[fehguy]

Good feedback on this. Two thoughts.

First, @darrelmiller’s suggestion is interesting as it can be used to compose many different types into an operation. It could become very verbose still, as one could potentially have dozens of constructs in the path identifier. I’ll keep thinking about how that could work.

Next, the notion of top-level definitions in the current 2.0 spec is a little confusing. For example as @dolmen pointed out, there is a responses section, but they’re not really responses–they are responseDefinitions. But we have a top-level accepts which applies to all operations defined in the spec.

I think these are different considerations. To address the 2nd item, in general, we have definitions and implementations at the root of the specification. Think of definitions as items which are always referenced elsewhere, and implementations as instances of requirements in the definition itself.

Some definitions:

• definitions
• securityDefinitions
• parameters
• responses

Some implementations:

• paths
• accepts/consumes
• info
• security
• host
• schemes
• basePaths
• tags

This is very confusing. The purpose for named definitions was that the schema could be used to ensure that all items under the, say, parameters definition were valid.

To simplify the structure, and to make room for reusable components as well as a hierarchial structure, I propose the following:

• The specification always supports a top-down overlay. This means that items defined at the top-level of the specification shall apply to all subordinate operations, except when overridden.
• The specification defines an explicit section for schemas, with the goal of reuse

Proposed structural changes

# implementations
info:
  # info object

# some implementations omitted for clarity
basePath:
  # basePath
tags:
  # - tag object
paths:
  # paths object
parameters:
  # parameters which apply to all operations
responses:
  # responses which apply to all operations
responseHeaders:
  # headers to be returned in all responses
security:
  # security requirements which apply to all operations
# definitions
schemas:
  definitions:
    # payload definition objects
  parameters:
    # parameters objects
  responses:
    # responses objects
  responseHeaders:
    # headers returned in responses
  security:
    # security definitions

In the proposed structure, we now have a single schemas section which allows us to put all reusable components in a single section. It also makes it possible to have the new parameters and responses section, which will give maximum reusability and readability.

If a top-level response is defined, say with 404 as the key, then an operation can override it by defining a new 404 response definition. There is no deletion of top-level items inside an operation.