Unable To Reference Custom Parameter Definitions about play-swagger HOT 8 CLOSED

That works! It's a little more verbose and less centrally controlled, but it's a viable workaround for me. I didn't even have to remove the name definition from the shared $ref definition. This is consistent with the Swagger spec, which says, "If there are conflicts between the referenced definition and this Path Item's definition, the behavior is undefined." Since I use the same name in both places, you can at least make the argument that there's no conflict. Leaving the name in the shared definition can therefore be used to ensure that the definition is not used with some other parameter name.

Thanks!

from play-swagger.

I think you have - $ref: "#/parameters/domain in your list of parameters, and json is complaining that it couldn't find the name element in it. Don't know what you trying achieve with that line

from play-swagger.

@kailuowang The Swagger Specification allows you to define parameters and several other structures for reuse. As my api requires that header at... basically every single endpoint, I'd like to avoid copy-pasting it every time.

For an example, I tweaked one of the sample Swagger yaml files to include the parameter:

swagger: '2.0'
info:
  version: 1.0.0
  title: PetStore on Heroku
  description: |
    **This example has a working backend hosted in Heroku**

    You can try all HTTP operation described in this Swagger spec.

    Find source code of this API [here](https://github.com/mohsen1/petstore-api)
host: petstore-api.herokuapp.com
basePath: /pet
schemes:
  - http
  - https
consumes:
  - application/json
  - text/xml
produces:
  - application/json
  - text/html
parameters:
  domain:
    name: "X-VirtualDomain"
    in: header
    description: The domain (account) you're attempting to interact with.
    required: true
    type: string
paths:
  /:
    get:
      parameters:
        - $ref: "#/parameters/domain"
        - name: limit
          in: query
          description: number of pets to return
          type: integer
          default: 11
          minimum: 11
          maximum: 10000
      responses:
        200:
          description:  List all pets
          schema:
            title: Pets
            type: array
            items:
              $ref: '#/definitions/Pet'
    post:
      parameters:
        - $ref: "#/parameters/domain"
        - name: pet
          in: body
          description: The pet JSON you want to post
          schema:
            $ref: '#/definitions/Pet'
          required: true
      responses:
        200:
          description: Make a new pet
    put:
      parameters:
        - $ref: "#/parameters/domain"
        - name: pet
          in: body
          description: The pet JSON you want to post
          schema:
            $ref: '#/definitions/Pet'
          required: true
      responses:
        200:
          description: Updates the pet
  /{petId}:
    get:
      parameters:
        - $ref: "#/parameters/domain"
        - name: petId
          in: path
          type: string
          description: ID of the pet
          required: true
      responses:
        200:
          description: Sends the pet with pet Id

definitions:
  Pet:
    type: object
    properties:
      name:
        type: string
      birthday:
        type: integer
        format: int32

If you copy-paste that into http://editor.swagger.io/#/ you can see that swagger accepts parameter references with the same effect as copy-pasting the parameter definition

from play-swagger.

I see. this is a bug at the play-swagger side, our json processing doesn't recognize such heterogeneous parameter list. In particular here is the code that failed

from play-swagger.

The same problem exists for query parameters that are included in the function signature in the routes file. The operation ends up with a parameter definition generated from the signature in the routes file and another defined by the $ref. The Swagger UI seems to detect that there are two definitions for the same parameter and ignores the latter, but I think play-swagger should override the generated definition with the one specified by $ref. This means peering into the reference to obtain the parameter's name and in values.
I'm new to Scala, Swagger, and Play (and by implication, play-swagger), so I'm not quite sure how to proceed. I guess the first question is whether I should create a new issue.

from play-swagger.

@JessePelton your situation is a bit different, as you want to override one generated by play-swagger while the original issue is about adding a new one by $ref. I wonder if you add the $ref inside the name what happens?
like

- name: email
  $ref: "#/parameters/email"

and in the shared $ref definition you don't define the name.

If that doesn't work than we will have to change play-swagger to read base yaml before doing the merge, which would not be a trivial change as above.

from play-swagger.

Not so workable after all. https://editor.swagger.io/ reports that the generated documentation is invalid because of the additional properties alongside the $ref. Worse, this prevents the swagger-ui "Try it" feature from working.

So...should I create a new issue?

from play-swagger.

Yeah a new issue would be great. One solution would be having swagger automatically remove all other attributes after the merge between the comment yaml and the autogenerated yaml if it sees a $ref property.

from play-swagger.