Allow shorthand $ref for parameters and responses

[mohsen1]

This is 2.1 proposal

In 2.0 we have a shorthand definition for schemas. If user do not provide #/definitions/ prefix, we will prepend it to their value in $ref if it's a schema value.

This should work for parameters and responses too

Example:

swagger: '2.1'
info:
  version: "1.0.0"
  title: shorthand ref example
paths:
  /:
    get:
      parameters:
        - $ref: size
      responses:
        $ref: 200


responses:
  200:
    description: Success

parameters: 
  size:
    name: size
    in: query
    required: true
    type: string

Resolver should understand the context of $ref and look in proper object.

Related to #132

[webron]

Isn't that a tooling issue? The output JSON will still have the full $ref, no?

[mohsen1]

no, the output JSON right now does not had full $ref for schemas

[webron]

So right now in the editor, if you have in YAML $ref: MyModel it would translate to a JSON like "$ref" : "MyModel"?

[mohsen1]

yes.

[webron]

I see. I need to investigate JSON Reference a bit more before knowing if it is technically possible, but if it is, sure, I'm all for it.

[mohsen1]

Is this shorthand syntax even documented for 2.0?

[webron]

I'm not sure what you mean by "shorthand" documentation (I feel may we may be using the same term for a different thing).

Basically, whatever is defined by http://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03 should be acceptable.

[mohsen1]

We decided to have a non-standard way of doing $refs. Basically, $ref: Person would be a shorthand for $ref: "#/defintions/Person". I thought this was part of 2.0. @fehguy Do you remember when we made this desiccation?

[webron]

I think the problem with that is that there are several sections of the spec that can be referred to - definitions, securityDefinitions, parameterDefinitions and responseDefinitions.

Theoretically, the location of the reference can be inferred from referencing object, but I fear that may overly complicate tools that need to read such specs.

I definitely understand the benefits of it, just think we need to weigh in the pros and cons.

[mohsen1]

@whitlockjc is writing the tool to resolve all $refs in Swagger Tools. He can talk more about how this impacts tooling.

[whitlockjc]

From a tooling perspective, supporting it would be confusing and painful in my opinion. If $ref support is inherited from JSON Schema like the Swagger docs say it is, the $ref value should be a JSON Pointer string, or a URI pointing somewhere in the existing document or to some other document (and optionally some location in that document). Anything else is a deviation (confusing) and needs special casing from a tooling perspective (painful).

We need to ask ourselves what we're trying to accomplish here. If it's a few less keystrokes, I don't think it's worth it. If it's something else more tangible, we should talk a bit more.

[jharmn]

Agree with @whitlockjc here. Especially with clarity recently added in guidelines/REUSE.md, this would clearly cause issues with file/uri issues.
With a renewed emphasis on separate files for definitions (a must in microservice environments with shared definitions), I can't see this working out.

Closing, as this is pretty old and seems like a non-starter. Re-open if you'd like to debate anything here.

[webron]

We just need to remember to put the same restriction in the current version in the next one as well (2.0 explicitly prohibits it, even though it is supported by JSON References).

[jharmn]

@webron JSON Reference allows for adding root-level elements, and referring to them directly (which maybe shouldn't be allowed, but @whitlockjc would probably disagree):

paths:
  /:
    get:
      parameters:
        - $ref: size
size:
  name: size
  in: query
  required: true
  type: string

The OP was suggesting something very different, which is to infer #/definitions/parameters/ to be prepended onto size. This is the issue that seems to be a non-starter, due to a lack of conformance to JSON Reference, and overall tooling confusion.

[webron]

I believe the author refers to inline vs canonical dereferencing as defined at http://json-schema.org/latest/json-schema-core.html#anchor30 - and we're decided to explicitly support only canonical iirc.

[whitlockjc]

My agreement depends on what we call a reference. If it's a JSON Reference, then a reference that does not start with a # is treated as a URI and a URI with a value of size is treated as a relative reference to a resource named size relative to the current document, no different than ./size. (I could be wrong but I remember reading this and the URI libraries I've used seem to conform to this as well.) If we come up with our own standard for references, I'm sure we could make shorthand make sense however we deem fit.

Node.js (url.parse)

URL.parse('Pet')
Url {
  protocol: null,
  slashes: null,
  auth: null,
  host: null,
  port: null,
  hostname: null,
  hash: null,
  search: null,
  query: null,
  pathname: 'Pet',
  path: 'Pet',
  href: 'Pet' }

Node.js (uri-js)

URI.parse('Pet')
{ scheme: undefined,
  userinfo: undefined,
  host: undefined,
  port: undefined,
  path: 'Pet',
  query: undefined,
  fragment: undefined,
  reference: 'relative' }

[whitlockjc]

I do agree with @webron that JSON Schema muddied the waters.