goa icon indicating copy to clipboard operation
goa copied to clipboard

Wrong type detect for Example of a String field in YAML

Open xlab opened this issue 4 years ago • 11 comments

Hello! I'm trying to generate API spec for a design like this:

package design

import (
	. "goa.design/goa/v3/dsl"
)

var _ = API("APITest", func() {

})

var _ = Service("ServiceTest", func() {
	Method("Main", func() {
		Payload(func() {
			Attribute("field1", String, func() {
				Example("0xffff")
			})
			Attribute("field2", String, func() {
				Example(`"0xffff"`)
			})
			Attribute("field3", String, func() {
				Example("0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498")
			})
			Attribute("field4", String, func() {
				Example(`"0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498"`)
			})
		})

		HTTP(func() {
			GET("/")
		})
	})
})

The problem is that the generated Swagger spec looks like this:

  ServiceTestMainRequestBody:
    title: ServiceTestMainRequestBody
    type: object
    properties:
      field1:
        type: string
        example: "0xffff"
      field2:
        type: string
        example: '"0xffff"'
      field3:
        type: string
        example: 0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498
      field4:
        type: string
        example: '"0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498"'
    example:
      field1: "0xffff"
      field2: '"0xffff"'
      field3: 0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498
      field4: '"0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498"'

As you can see, for some reason field3 is treated as a number! Which will affect the generated documentation later. And for some reason field1 is treated correctly.

So that's clearly a bug, I'm not sure why Goa tries to dynamically detect type if it is declared as String already in the spec. @raphael I need your help at this point :)

xlab avatar Jan 13 '20 14:01 xlab

Clarification: the bug is somewhere near YAML generation, because JSON looks ok:

   "definitions": {
        "ServiceTestMainRequestBody": {
            "title": "ServiceTestMainRequestBody",
            "type": "object",
            "properties": {
                "field1": {
                    "type": "string",
                    "example": "0xffff"
                },
                "field2": {
                    "type": "string",
                    "example": "\"0xffff\""
                },
                "field3": {
                    "type": "string",
                    "example": "0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498"
                },
                "field4": {
                    "type": "string",
                    "example": "\"0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498\""
                }
            },
            "example": {
                "field1": "0xffff",
                "field2": "\"0xffff\"",
                "field3": "0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498",
                "field4": "\"0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498\""
            }
        }
    }

xlab avatar Jan 13 '20 23:01 xlab

Thank you for the report! Goa does not do any type inference. This looks like some weirdness in the YAML package that Goa uses (or Goa not using it correctly).

raphael avatar Jan 14 '20 01:01 raphael

@raphael actually since YAML accepts strings only, we can actually put the "" under every field and solving this issue, what do you think?

saniales avatar May 13 '20 12:05 saniales

@saniales if that works then sounds good! I believe the issue is that sometimes the YAML package will add these quotes and sometimes it won't which means that if we always add them it might double escape them?

raphael avatar May 19 '20 21:05 raphael

@saniales

actually since YAML accepts strings only

Well not only strings - YAML natively encodes scalars (such as strings, integers, and floats)

xlab avatar May 20 '20 07:05 xlab

@raphael @xlab what we actually care is not to be pure about yaml types, instead that they are shown correctly in openapi spec, being string the type we can stringify everything and it should work

saniales avatar May 20 '20 07:05 saniales

@saniales I agree, that might be the approach

xlab avatar May 20 '20 07:05 xlab

@saniales give it a shot, I suspect that the result is going to be that they are all strings but that "sometimes" the string will be quoted which may or may not be an issue for OpenAPI spec examples.

raphael avatar May 25 '20 00:05 raphael

will give it a shot in the coming days

saniales avatar May 25 '20 09:05 saniales

I confirm that this can be solved by using single quotes only with string values

And I also confirm that JSON generated openapi is not affected by this, only YAML

saniales avatar Dec 28 '21 23:12 saniales

Would you care to make a PR that adds the quote?

raphael avatar Jan 05 '22 22:01 raphael