Structural improvements: inheritance on paths and its sublevels

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 ...)

[arno-di-loreto]

Thanks @IvanGoncharov . I’ve replaced the full example by a link to a gist.

[IvanGoncharov]

@arno-di-loreto Great proposal, it removes a lot of unnecessary duplication from Swagger files. But I totally agree with @webron on:

Another issue with both globals and consistency is that they are already inconsistent. security is overridden, parameters are added, for example.

But it’s very easy to solve if we support default property along side with shared. And it will be very simple algorithm for figuring out values for particular operation:

1. All properties inside operation used as initial values.
2. Go one level up.
3. Values from default set as property values but only if matching property is undefined at the moment.
4. Values from shared prepend to the current value of the property.
5. Repeat steps 2-4.

So path-level parameters from 2.0 will move to path-level shared. And root-level security will move to paths-level default. It will also allow for many other things that not possible in 2.0. For example, to define global OAuth scopes but allow individual operations to add their own.

P.S. @arno-di-loreto Such big code samples make Github issues harder to scroll. Can you please replace sample from your last comment with a link to a Gist?