Problem statement

Although not documented here https://goswagger.io/use/spec/model.html the codescan attempts to parse the // Enum: comments but the result is not as expected. Also, the generated documentation comment is impossible to parse when enum items are strings and contain spaces or special chars.

Steps to reproduce

here is a spec that illustrates both problems:

swagger spec:

swagger: "2.0"
info:
  version: "1.0.0"
  title: "Test"

paths: {}
definitions:
  test_enum:
    type: object
    properties:
      enum_string_field:
        type: string
        enum: ["1", "with space", 'with "quotes"']
      enum_int_field:
        type: integer
        enum: [-1, 2, 6000]

When code is generated using this spec (go run cmd/swagger/swagger.go generate model -t test/ -f test/swagger.yml) we get the following result:

// TestEnum test enum
//
// swagger:model test_enum
type TestEnum struct {

	// enum int field
	// Enum: [-1 2 6000]
	EnumIntField int64 `json:"enum_int_field,omitempty"`

	// enum string field
	// Enum: [1 with space with "quotes"]
	EnumStringField string `json:"enum_string_field,omitempty"`
}

It is already clear that the EnumStringField items can not be parsed because it is impossible to reconstruct where the spaces were initially. However, here is the generate spec result (go run cmd/swagger/swagger.go generate spec -w test/ --scan-models --include=test -o test/swagger-gen.yml):

definitions:
    test_enum:
        description: TestEnum test enum
        properties:
            enum_int_field:
                description: enum int field
                enum:
                    - '[-1 2 6000]'
                format: int64
                type: integer
                x-go-name: EnumIntField
            enum_string_field:
                description: enum string field
                enum:
                    - '[1 with space with "quotes"]'
                type: string
                x-go-name: EnumStringField
        type: object
        x-go-name: TestEnum
        x-go-package: github.com/go-swagger/go-swagger/test/models
paths: {}
swagger: "2.0"

And we see how enum are parsed as a single item.

Fix proposal.

First we need a better documentation format for the items, and we can use json:

type TestEnum struct {

	// enum int field
	// Enum: [-1,2,6000]
	EnumIntField int64 `json:"enum_int_field,omitempty"`

	// enum string field
	// Enum: ["1","with space","with \"quotes\""]
	EnumStringField string `json:"enum_string_field,omitempty"`
}

Then we can fix the parsing issue.

Environment

swagger version: v0.30.5-25-g10db6e00
go version: go1.18.3 linux/amd64
OS: Ubuntu 20.04