Structural improvements: enhance schemes, host and basePath handling

[arno-di-loreto]

On OpenAPI spec current version, schemes, host and basePath are handled this way

• schemes, host and basePath are declared on root level
• schemes can be overidden on operation

schemes:
  - http
  - https
host: api.domain.com
basePath: /basepath
paths:
  /resources:
    get:
      schemes:
        - https

With current version:

• you can only declare one environment in a OpenAPI spec file
• all paths and operations shares the same host and basePath
• you can only override schemes

Proposed enhancement

1 - Create a new urls object:

urls:
    # (new) Grouping schemes, host and basePath and add optional environments handling.
    schemes:
      # (existing) Moved from root to urls.
      # These schemes are used by all environments if multiple environments are defined.
    host:
      # (existing) Moved from root to urls.
      # This host is used by all environments if multiple environments are defined.
    basePath:
      # (existing) Moved from root to urls.
      # Base path used all environments if multiple environments are defined.
    externalDocs:
      # (new) link to some external documentation
    defaultEnvironment:
      # (new) default environment name if multiple environments are defined
    {environment name}:
      # (new) optional definition per environment
      schemes:
        # (new) schemes for this environment.
        #  Overrides urls.schemes
      host:
        # (new) host for this environnement
        # Overrides urls.host
      basePath:
        # (new) base path for this environment
        # Overrides urls.basePath
      externalDoc:
        # (new) link to some external documentation for this environment

2 - use this new object in paths and its sub-levels (cf. OAI/sig-moonwalk#115 )

# schemes, host and basePath are removed from root
paths:
  # url object can be defined on any level in paths object (paths, path, operation)
  urls:
    # will apply on all paths and operation
    schemes:
      - http
      - https
    basePath: /basepath
    sandbox:
       # host for sandbox environment
       host: api.sandbox.domain.com
    production:
       # host for production environment
       host: api.domain.com
  /resources:
    urls:
      # will apply on all operations
      # declared properties override paths urls properties
      schemes:
        # overriding paths schemes
        - http
    post:
      urls:
        # will apply on this operation
        # declared properties override /resources urls properties
        schemes:
          # overriding /resources schemes
          - https 
        sandbox:
          # overriding host for sandbox environment 
          host: api.sandbox.specific.domain.com
        production:
          # overriding host for production environment
          host: api.specific.domain.com 

[darrelmiller]

@arno-di-loreto Have you seen this PR? It partially addresses what you are looking for. However, it doesn't explicitly attempt to address the environments problem, although you could use it to do that. Personally, I would prefer to see environments dealt with in something like apis.json rather than increase the scope of the OpenAPI spec even further.

[arno-di-loreto]

@darrelmiller I've checked issues but not PR (doh!).
I've thought about apis.json on this topic, it totally make sense if you don't need to override thing in your api definition (but do we really need that). So a second idea would be to remove these data from the spec :-)

[arno-di-loreto]

parent #560

[webron]

We've decided to not support environments.

As @darrelmiller mentioned, this is covered by #646, but also covered by #604. The main difference is that #646 needs to be applied to #604 as the structure. Since this is work in progress, we've decided to iterate at the end and clean such things out. However, for easier tracking I'll open a ticket to help us track such changes.