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