ruby-grape / grape-swagger

Add OAPI/swagger v2.0 compliant documentation to your grape API

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

when importing swagger into postman I always get x-www-urlencoded body rather than json

tansaku opened this issue · comments

Apologies if specific to the postman software, but I'm noticing that when we import swagger docs into postman, that the formData seems to come in in x-www-form-urlencoded format, rather than as a json body - I've been trying and failing to find some import setting that affects this (I have also reached out to the postman folks), but I wonder if I just need the correct swagger grape setting. For example this is a snippet of the grape swagger we're using:

        desc 'make a payment', {
          header: { 'Content-Type' => 'application/json' },
        }
        params do
          requires :data, type: Hash do  #  <--- could it be because we're using a hash here?
            requires :check_id, type: String, documentation: { example: '8989ytuyiuy', desc: 'Check Unique Idenitifier'}
            requires :amount_cents, type: Integer, documentation: 

which generated swagger like this:

    "/public/payments": {
      "post": {
        "description": "Pay a check",
        "produces": [
          "application/json"
        ],
        "consumes": [
          "application/json"
        ],
        "parameters": [
          {
            "in": "formData",
            "name": "data[check_id]",
            "description": "Check Unique Idenitifier",
            "type": "string",
            "required": true,
            "example": "2342qewt23werwfesd"
          },

but in postman it always show up like this:

data[check_id]:<string>
data[amount_cents]:<integer>
...

rather than

{
	"data": {
		"amount_cents": 0,
		"check_id": "<string>",
                 ...
	}
}

I just wondered if there were other settings that would influence the swagger data format so that it was more JSONish rather than x-www-form-urlencoded? maybe just the way postman interprets the swagger standard I guess ...?

Many thanks in advance

maybe related to this formData issue: #792 perhaps currently params are always set as in type formData when it would be useful to have the option to set them as body ?

I also posted this question to the postman community forum: https://community.postman.com/t/form-data-style-when-importing-swagger-into-postman/25143 postman support suggested the following:

not using formData and instead declare the content type and describe the schema similar to what they do here in Swagger's documentation.

https://swagger.io/docs/specification/2-0/describing-request-body/

aha, fixed it! here's the fix:

        desc 'make a payment', {
          header: { 'Content-Type' => 'application/json' },
        }
        params do
          requires :data, type: Hash, documentation: { in: 'body' } do  #  <--- override `in` here
            requires :check_id, type: String, documentation: { example: '8989ytuyiuy', desc: 'Check Unique Idenitifier'}
            requires :amount_cents, type: Integer, documentation: