Structural improvements: inheritance on paths and its sublevels

[arno-di-loreto]

Based on @fehguy structure modification proposition on OAI/OpenAPI-Specification#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]

parent OAI/OpenAPI-Specification#560

[webron]

It definitely looks cleaner, however:

• tags belong under the Info Object and not the Paths Object. They are not a global definition of tags that are applied to all paths but a documentation of what the tags mean.
• I'm not a big fan of combining the globals at the same level of the paths. It can end up being messy, having too many things under one node, plus you could have parameters, /path, security, /path2 and that's just difficult to read. I get what you're trying to do with the other tickets and inheritance/overriding of the globals, but I don't think that's enough to justify it. As an alternative, we can either collect all the globals under a key (globals?) at the same level as paths, info and so on, or we can move the entire set of globals and paths under a common node (root?), having the globals defined alongside the paths key, keeping a similar structure to what it is now, just pushing it down a node.

[arno-di-loreto]

• I did not move tag documentation to paths. I only add the possibility of using tag on global, path and operations level (with current version we can only set tags on operation level).
• Concerning globals (and their equivalent on sublevels), the most important thing (for me) is that we can define things on all levels (global/path/operation/response) with inheritance (like with existing parameters).
• But I'm very fond of consistency :-) that's why I propose that : to have all these "shared things" defined the same way on all levels. But you're totally right it may be difficult to read. So what about something like that (applying globals idea on each level to group "shared things" and make the spec more easy to read). In the end it would be just like parameters on path level in the existing version but extended to all shared things (definitely need a better name):

paths:
  globals (or shared or another word):
    # Tags, parameters, responses, responses headers, security
    # (which were on root on Tony's proposal) and new others applying
    # to all paths
    # Everything can be overridden by sub levels.
  {/paths}:
    globals (or shared or another word):
      # Tags, parameters, responses, responses headers,
      # security and new other things applying to all operations
      # Everything can be overridden by sub levels.
    {operation like get/post/...}:
        responses:
          globals (or shared or another word):
            # Responses headers and new other things applying to all responses
            # Everything can be overridden by sub levels.
        {http status | default):
            # response object

[webron]

• Got it, wasn't clear in the original post. I'm ok with that.
• I don't see where it would make sense to have something inherited to the response level. I believe in a different ticket you mentioned headers but that holds a set of other potential issues (which we already may have introduced in a different ticket). I'll add the comments to OAI/OpenAPI-Specification#690. However, is there anything else that would be inherited to the response level?
• Another issue with both globals and consistency is that they are already inconsistent. security is overridden, parameters is added, for example.
• I like the structure consistency you suggest, I don't like the somewhat bloat it adds. From a technical point of view, there shouldn't be a problem supporting it. Manually writing it can be a bit of a pain (you've written tutorials about the spec, try writing the same examples with the new construct). Consistency is important, but so is ease-of-write (especially for the design-first approach).

[arno-di-loreto]

First things first: thank you and all the team for reading my issues and giving feedback, there are so many issues and comments in this repo! It took me a long time to figure which of my ideas were already there ... and I missed some of them :-)

• in addition to headers, produces could also be inherited to the response level
• you get a point about inconsistency between security and parameters inheritance behaviour, but that's already the case in version 2 :-)
• as a writer of OpenAPI 2.0 specification, I really liked using this "3.0 version" applying (see below) this inheritance concept :-), easier to write and read because I don't have to rewrite too many things. It's finally only expanding the path/operation parameters principle to everything.
  • All shared object are in shared on each level
  • On path level:
  • userAgent param is set once for all the API instead of being defined on each path
  • X-Rate-Limit-Remaining and X-Rate-Limit-Reset are set once for all the API instead of being defined on each response
  • 500 and default responses are set once for all the API instead of beging defined on each operation
  • On path level for /persons/{username}:
  • username is defined once (already possible in 2.0)
  • 404 response is defined once too instead of having to define it for both get and delete
  • On responses level for post /js-less-persons:
  • produces is overriden for all responses
  • X-PARTNER-HEADER is defined for all responses (including global ones)
  • Overriding produces on 200 response level on get /image/{imageId}
  • Trying to use $ref for all reusable thing like security, I like the idea but don't know how it could work for security when you using Oauth 2 scopes (see paths.shared.security)
  • All reusable definitions (definitions, parameters, securitySchemes, ...) are moved to allDefinition, not fond of the name and I'm wondering if it's useful to do that

Here's the full 3.0 example based on the last file of part 6 of my tutorial:

https://gist.github.com/arno-di-loreto/707f15ff819428bdbd7a3acab3bc8333

[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?

[arno-di-loreto]

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

[handrews]

I'm moving this to Moonwalk as big structural changes cannot happen before then.