Structural improvements: inheritance on paths and its sublevels

[arno-di-loreto]

Based on @fehguy structure modification proposition on #563 and my ideas gathered while writing OpenAPI spec and writing my OpenAPI spec tutorial, I propose a new structure for the document.

Tony's proposal (focus on paths and what it needs):

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

On root we only keep:

• paths: The API's description (improved paths, see below)
• schemas: All reusable objects used to describe to API

version:
  # OpenAPI version used by this document, replace swagger

info:
  # existing info object + externalDocs which was on root level
  # ... same properties as existing info object
  externalDocs:
  # (existing) Moving externalDocs from root to info

paths:
  # improved paths object (see below) contains what was on root
  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

schemas:
  definitions:
    # payload definition objects
  parameters:
    # parameters objects
  responses:
    # responses objects
  responseHeaders:
    # headers returned in responses
  security:
    # security definitions

On paths, the idea is to extend what we already have with parameters declaration on path and operation level to everything that can be declared for an operation (parameters, responses, headers, ...) on all levels:

What we have now:

paths:
  /resources/{parameters}:
    parameters:
      # parameters apply to all operations
    get:
      parameters:
        # parameters apply to this operation

Extending this principle to all levels and properties in paths and its sub-level:

paths:
  # Everything on this level which is not a path, apply to all paths
  # We put here the things which were on root on Tony's proposal. 
  # Everything can be overridden by sub levels.
  (... various declarations like tags, parameters, responses, responses headers, security
  and new others applying to all paths......)
  {/paths}:
  # (existing) path object
    # Everything on this level which is not an operation, apply to all operations.
    # Everything can be overridden by sub levels.
    (... various declarations like tags, parameters, responses, responses headers,
     security and new others applying to all operations......)
    {operation like get/post/...}:
      (...operation properties, can override what was described on the upper levels ...)
      responses:
        # Everything on this level which is not a response, apply to all responses. 
        # Everything can be overridden by sub levels.
        (... various declarations like responses headers and 
         new others applying to all responses......)
        {http status | default):
            (...operation properties, can override what was 
             described on the upper levels ...)