grape-swagger Using an entity to represent a post body in params

Hey there! Thanks so much for all the hard work that goes into grape-swagger and its related projects; they're a huge help.

One thing that I've been running into, and it's something of a cross-cutting concern so I wasn't quite sure whether to put it here or in grape-swagger-entity, is a common problem I'm running into. In other frameworks I've used, you can specify a body's parameter set as an entity or an object. For example, I might have LoginRequest, which specifies username, plaintext, that sort of thing. However, grape-swagger does not make it obvious as to how I would do this and I get a lot of weird error messages (code deep in grape-swagger that gets nils it's not expecting, etc.) when I try to just say "the body parameters for this are just this entity right here".

I know Swagger can describe it, because I've written Swagger documents by hand that do so. I just can't figure out how to make grape-swagger do it, or if the library can at all? Maybe this is totally doable and I'm just goofy, and if so I would love a pointer! But the best I've found is to have a single parameter, conventionally request, and dig into params[:request] for it. Which isn't bad, but the experience of it is kind of weird when I use a client library where I'm passing a named request parameter instead of just username and plaintext. It feels more clunky than the rest of Grape and grape-swagger so I'm wondering either if I'm missing something or if this is as-designed.

Thanks again!

Dec 12 '17 19:12 eropple

Bump; it's been about a month and some guidance would be really appreciated.

Jan 21 '18 21:01 eropple

@eropple Hello, can you provide some examples of code or spec for this feature?

Jan 21 '18 22:01 kzaitsev

I'd like to generate an option that looks like this (from the canonical petstore-expanded.yaml):

    post:
      description: Creates a new pet in the store.  Duplicates are allowed
      operationId: addPet
      parameters:
        - name: pet
          in: body
          description: Pet to add to the store
          required: true
          schema:
            $ref: '#/definitions/NewPet'

I can't for the life of me figure out how to generate this.

Jan 22 '18 03:01 eropple

I'm in the same boat. All of the swagger doc is generated with the params set to in: "formData" when it's actually in the JSON payload.

Jul 09 '18 02:07 bobbytables

please have a look at this api_swagger_v2_param_type_body_spec, the trick is to set at minimum one parameter with param_type: 'body'

Jul 09 '18 08:07 LeFnord

Is there some way to specify that the definition should not be wrapped in another definition?

In the example in the spec, you get '#/definitions/ApiResponse', wrapped in '#/definitions/postWithEntityParam'. I would like to reference a definition in the parameters directly without the wrapping (so that the request body is directly the defined object).

Oct 26 '18 10:10 joerghaubrichs

@joerghaubrichs

Here is an example w/o the nesting.

  params do
    requires :name, type: String, desc: 'Project name', documentation: {param_type: 'body'}
    optional :description, type: String, desc: 'Project description'
    optional :members, type: Array do
      requires :user_id, type: Integer, desc: 'User ID'
      requires :role, type: Symbol, values: [:viewer, :user, :manager], desc: 'Role for the user'
    end
  end

So simply adding `documentation: {param_type: 'body'} causes grape-swagger to create a ad-hoc entity using all of the params. (and not nested)

Feb 05 '19 01:02 urkle

Is there a way to specify what the name of the generated entity can be? I tried a few different symbols but to no avail. For example, it will generate an entity under definitions with a name like postAdminV1Customers, which isn't very user friendly.