diff --git a/README.md b/README.md index 054e36ec6..6ed20e799 100644 --- a/README.md +++ b/README.md @@ -900,6 +900,36 @@ Make it OR condition // @Security OAuth2Application[write, admin] || APIKeyAuth ``` +### Generate enum types from enum constants + +You can generate enums from ordered constants. Each enum variant can have a comment, an override name, or both. This works with both iota-defined and manually defined constants. + +```go +type Difficulty string + +const ( + Easy Difficulty = "easy" // You can add a comment to the enum variant. + Medium Difficulty = "medium" // @name MediumDifficulty + Hard Difficulty = "hard" // @name HardDifficulty You can have a name override and a comment. +) + +type Class int + +const ( + First Class = iota // @name FirstClass + Second // Name override and comment rules apply here just as above. + Third // @name ThirdClass This one has a name override and a comment. +) + +// There is no need to add `enums:"..."` to the fields, it is automatically generated from the ordered consts. +type Quiz struct { + Difficulty Difficulty + Class Class + Questions []string + Answers []string +} +``` + ### Add a description for enum items diff --git a/enums_test.go b/enums_test.go index e3456378e..533657447 100644 --- a/enums_test.go +++ b/enums_test.go @@ -17,9 +17,11 @@ func TestParseGlobalEnums(t *testing.T) { p := New() err = p.ParseAPI(searchDir, mainAPIFile, defaultParseDepth) assert.NoError(t, err) + b, err := json.MarshalIndent(p.swagger, "", " ") assert.NoError(t, err) assert.Equal(t, string(expected), string(b)) + constsPath := "github.com/swaggo/swag/testdata/enums/consts" assert.Equal(t, 64, p.packages.packages[constsPath].ConstTable["uintSize"].Value) assert.Equal(t, int32(62), p.packages.packages[constsPath].ConstTable["maxBase"].Value) @@ -30,4 +32,13 @@ func TestParseGlobalEnums(t *testing.T) { assert.Equal(t, "aa\nbb\u8888cc", p.packages.packages[constsPath].ConstTable["escapestr"].Value) assert.Equal(t, 1_000_000, p.packages.packages[constsPath].ConstTable["underscored"].Value) assert.Equal(t, 0b10001000, p.packages.packages[constsPath].ConstTable["binaryInteger"].Value) + + typesPath := "github.com/swaggo/swag/testdata/enums/types" + difficultyEnums := p.packages.packages[typesPath].TypeDefinitions["Difficulty"].Enums + assert.Equal(t, "Easy", difficultyEnums[0].key) + assert.Equal(t, "", difficultyEnums[0].Comment) + assert.Equal(t, "Medium", difficultyEnums[1].key) + assert.Equal(t, "This one also has a comment", difficultyEnums[1].Comment) + assert.Equal(t, "DifficultyHard", difficultyEnums[2].key) + assert.Equal(t, "This means really hard", difficultyEnums[2].Comment) } diff --git a/testdata/enums/types/model.go b/testdata/enums/types/model.go index a6cba9cd1..f67d6cae4 100644 --- a/testdata/enums/types/model.go +++ b/testdata/enums/types/model.go @@ -63,3 +63,11 @@ type PersonWithArrayEnum struct { Mask []Mask Type Type } + +type Difficulty string + +const ( + DifficultyEasy Difficulty = "easy" // @name Easy + DifficultyMedium Difficulty = "medium" // @Name Medium This one also has a comment + DifficultyHard Difficulty = "hard" // This means really hard +)