From 7ca47390b3cf97f4d5cadc627fead49782f6c2b9 Mon Sep 17 00:00:00 2001 From: Shane O'Donovan Date: Sat, 9 Oct 2021 00:22:39 +0100 Subject: [PATCH 1/5] Fix: Array of enums wasn't being documented --- docparse/jsonschema.go | 15 +++++++++++++-- testdata/openapi2/src/params-embed/in.go | 7 +++++++ testdata/openapi2/src/params-embed/want.yaml | 20 +++++++++++++++----- 3 files changed, 35 insertions(+), 7 deletions(-) diff --git a/docparse/jsonschema.go b/docparse/jsonschema.go index 70ff5ef..ffd0eb7 100644 --- a/docparse/jsonschema.go +++ b/docparse/jsonschema.go @@ -507,6 +507,12 @@ arrayStart: p.Items = &Schema{Type: JSONSchemaType(typ.Name)} + // Generally an item is an enum rather than the array itself + if p.Enum != nil { + p.Items.Enum = p.Enum + p.Enum = nil + } + // Map []byte to []string. if typ.Name == "byte" { p.Items = nil @@ -556,10 +562,15 @@ arrayStart: return err } if t != "" { - p.Type = t - if isPrimitive(p.Type) { + if isPrimitive(t) { + if p.Items == nil { + p.Items = &Schema{} + } + p.Items.Type = t return nil } + // It's an array. Why are we changing its type here? + p.Type = t } sRef := lookup diff --git a/testdata/openapi2/src/params-embed/in.go b/testdata/openapi2/src/params-embed/in.go index 695bad6..a84ba3a 100644 --- a/testdata/openapi2/src/params-embed/in.go +++ b/testdata/openapi2/src/params-embed/in.go @@ -1,10 +1,17 @@ package params +type customType int64 + type common struct { // FieldTasks common description. // // {enum: name priority status description} FieldTasks []string `query:"fields[tasks]"` + + // CustomTypes common description. + // + // {enum: blue red yellow} + CustomTypes []customType `query:"customTypes"` } type queryRef struct { diff --git a/testdata/openapi2/src/params-embed/want.yaml b/testdata/openapi2/src/params-embed/want.yaml index ae24e1c..8debb90 100644 --- a/testdata/openapi2/src/params-embed/want.yaml +++ b/testdata/openapi2/src/params-embed/want.yaml @@ -27,11 +27,21 @@ paths: type: array items: type: string - enum: - - name - - priority - - status - - description + enum: + - name + - priority + - status + - description + - name: customTypes + in: query + description: CustomTypes common description. + type: array + items: + type: integer + enum: + - blue + - red + - yellow responses: 200: description: 200 OK (no data) From 6653a3670da024b49e5a95b686670b8350fafb3a Mon Sep 17 00:00:00 2001 From: Shane O'Donovan Date: Mon, 11 Oct 2021 11:35:34 +0100 Subject: [PATCH 2/5] fix --- docparse/jsonschema.go | 2 -- testdata/openapi2/src/params-embed/in.go | 7 +++++++ testdata/openapi2/src/params-embed/want.yaml | 11 ++++++++++- 3 files changed, 17 insertions(+), 3 deletions(-) diff --git a/docparse/jsonschema.go b/docparse/jsonschema.go index ffd0eb7..1c17fc5 100644 --- a/docparse/jsonschema.go +++ b/docparse/jsonschema.go @@ -569,8 +569,6 @@ arrayStart: p.Items.Type = t return nil } - // It's an array. Why are we changing its type here? - p.Type = t } sRef := lookup diff --git a/testdata/openapi2/src/params-embed/in.go b/testdata/openapi2/src/params-embed/in.go index a84ba3a..20ed506 100644 --- a/testdata/openapi2/src/params-embed/in.go +++ b/testdata/openapi2/src/params-embed/in.go @@ -2,6 +2,10 @@ package params type customType int64 +type magic interface{} + +type magics []magic + type common struct { // FieldTasks common description. // @@ -12,6 +16,9 @@ type common struct { // // {enum: blue red yellow} CustomTypes []customType `query:"customTypes"` + + // Magics common description. + Magics magics `query:"magics"` } type queryRef struct { diff --git a/testdata/openapi2/src/params-embed/want.yaml b/testdata/openapi2/src/params-embed/want.yaml index 8debb90..01ac9e5 100644 --- a/testdata/openapi2/src/params-embed/want.yaml +++ b/testdata/openapi2/src/params-embed/want.yaml @@ -21,6 +21,12 @@ paths: default: "10" minimum: 10 maximum: 100 + - name: magics + in: query + description: Magics common description. + type: array + items: + type: string - name: fields[tasks] in: query description: FieldTasks common description. @@ -45,4 +51,7 @@ paths: responses: 200: description: 200 OK (no data) -definitions: {} +definitions: + params-embed.magic: + title: magic + type: object From 5660926ad5faae19050ce6e8876f769cc1812e7f Mon Sep 17 00:00:00 2001 From: Shane O'Donovan Date: Mon, 11 Oct 2021 12:09:54 +0100 Subject: [PATCH 3/5] fix --- testdata/openapi2/src/params-embed/in.go | 9 +-------- testdata/openapi2/src/params-embed/want.yaml | 13 ++----------- 2 files changed, 3 insertions(+), 19 deletions(-) diff --git a/testdata/openapi2/src/params-embed/in.go b/testdata/openapi2/src/params-embed/in.go index 20ed506..7b86e97 100644 --- a/testdata/openapi2/src/params-embed/in.go +++ b/testdata/openapi2/src/params-embed/in.go @@ -1,10 +1,6 @@ package params -type customType int64 - -type magic interface{} - -type magics []magic +type customType string type common struct { // FieldTasks common description. @@ -16,9 +12,6 @@ type common struct { // // {enum: blue red yellow} CustomTypes []customType `query:"customTypes"` - - // Magics common description. - Magics magics `query:"magics"` } type queryRef struct { diff --git a/testdata/openapi2/src/params-embed/want.yaml b/testdata/openapi2/src/params-embed/want.yaml index 01ac9e5..5878f1e 100644 --- a/testdata/openapi2/src/params-embed/want.yaml +++ b/testdata/openapi2/src/params-embed/want.yaml @@ -21,12 +21,6 @@ paths: default: "10" minimum: 10 maximum: 100 - - name: magics - in: query - description: Magics common description. - type: array - items: - type: string - name: fields[tasks] in: query description: FieldTasks common description. @@ -43,7 +37,7 @@ paths: description: CustomTypes common description. type: array items: - type: integer + type: string enum: - blue - red @@ -51,7 +45,4 @@ paths: responses: 200: description: 200 OK (no data) -definitions: - params-embed.magic: - title: magic - type: object +definitions: {} From 5b506d5bc8873b77c758ecfc588e703aa2c34c4f Mon Sep 17 00:00:00 2001 From: Shane O'Donovan Date: Mon, 11 Oct 2021 12:20:01 +0100 Subject: [PATCH 4/5] cov --- docparse/jsonschema_test.go | 35 ++++++++++++++++++----------------- 1 file changed, 18 insertions(+), 17 deletions(-) diff --git a/docparse/jsonschema_test.go b/docparse/jsonschema_test.go index 8fb89c9..c4d102e 100644 --- a/docparse/jsonschema_test.go +++ b/docparse/jsonschema_test.go @@ -11,23 +11,24 @@ import ( func TestFieldToProperty(t *testing.T) { want := map[string]*Schema{ - "str": {Type: "string", Description: "Documented str field.\nNewline."}, - "byt": {Type: "string"}, - "r": {Type: "string"}, - "b": {Type: "boolean", Description: "Inline docs."}, - "fl": {Type: "number"}, - "err": {Type: "string"}, - "strP": {Type: "string"}, - "slice": {Type: "array", Items: &Schema{Type: "string"}}, - "sliceP": {Type: "array", Items: &Schema{Type: "string"}}, - "cstr": {Type: "string"}, - "cstrP": {Type: "string"}, - "bar": {Reference: "a.bar"}, - "barP": {Reference: "a.bar"}, - "pkg": {Reference: "mail.Address"}, - "pkgSlice": {Type: "array", Items: &Schema{Reference: "mail.Address"}}, - "pkgSliceP": {Type: "array", Items: &Schema{Reference: "mail.Address"}}, - "deeper": {Reference: "a.refAnother"}, + "str": {Type: "string", Description: "Documented str field.\nNewline."}, + "byt": {Type: "string"}, + "r": {Type: "string"}, + "b": {Type: "boolean", Description: "Inline docs."}, + "fl": {Type: "number"}, + "err": {Type: "string"}, + "strP": {Type: "string"}, + "slice": {Type: "array", Items: &Schema{Type: "string"}}, + "sliceP": {Type: "array", Items: &Schema{Type: "string"}}, + "sliceNoItems": {Type: "array"}, + "cstr": {Type: "string"}, + "cstrP": {Type: "string"}, + "bar": {Reference: "a.bar"}, + "barP": {Reference: "a.bar"}, + "pkg": {Reference: "mail.Address"}, + "pkgSlice": {Type: "array", Items: &Schema{Reference: "mail.Address"}}, + "pkgSliceP": {Type: "array", Items: &Schema{Reference: "mail.Address"}}, + "deeper": {Reference: "a.refAnother"}, "docs": {Type: "string", Description: "This has some documentation!", Required: []string{"docs"}, Enum: []string{"one", "two", "three", "four", "five", "six", "seven"}, From 829e9b839c505b6d8cd780b7469227abf036b4ac Mon Sep 17 00:00:00 2001 From: Shane O'Donovan Date: Mon, 11 Oct 2021 12:56:52 +0100 Subject: [PATCH 5/5] try to fix coverage --- docparse/jsonschema_test.go | 36 ++++++++++++++++++------------------ docparse/testdata/src/a/a.go | 1 + 2 files changed, 19 insertions(+), 18 deletions(-) diff --git a/docparse/jsonschema_test.go b/docparse/jsonschema_test.go index c4d102e..471e3b3 100644 --- a/docparse/jsonschema_test.go +++ b/docparse/jsonschema_test.go @@ -11,24 +11,24 @@ import ( func TestFieldToProperty(t *testing.T) { want := map[string]*Schema{ - "str": {Type: "string", Description: "Documented str field.\nNewline."}, - "byt": {Type: "string"}, - "r": {Type: "string"}, - "b": {Type: "boolean", Description: "Inline docs."}, - "fl": {Type: "number"}, - "err": {Type: "string"}, - "strP": {Type: "string"}, - "slice": {Type: "array", Items: &Schema{Type: "string"}}, - "sliceP": {Type: "array", Items: &Schema{Type: "string"}}, - "sliceNoItems": {Type: "array"}, - "cstr": {Type: "string"}, - "cstrP": {Type: "string"}, - "bar": {Reference: "a.bar"}, - "barP": {Reference: "a.bar"}, - "pkg": {Reference: "mail.Address"}, - "pkgSlice": {Type: "array", Items: &Schema{Reference: "mail.Address"}}, - "pkgSliceP": {Type: "array", Items: &Schema{Reference: "mail.Address"}}, - "deeper": {Reference: "a.refAnother"}, + "str": {Type: "string", Description: "Documented str field.\nNewline."}, + "byt": {Type: "string"}, + "r": {Type: "string"}, + "b": {Type: "boolean", Description: "Inline docs."}, + "fl": {Type: "number"}, + "err": {Type: "string"}, + "strP": {Type: "string"}, + "slice": {Type: "array", Items: &Schema{Type: "string"}}, + "sliceP": {Type: "array", Items: &Schema{Type: "string"}}, + "cstr": {Type: "string"}, + "cstrP": {Type: "string"}, + "bar": {Reference: "a.bar"}, + "barP": {Reference: "a.bar"}, + "pkg": {Reference: "mail.Address"}, + "pkgSlice": {Type: "array", Items: &Schema{Reference: "mail.Address"}}, + "pkgSliceP": {Type: "array", Items: &Schema{Reference: "mail.Address"}}, + "cSlice": {Type: "array", Items: &Schema{Type: "string"}}, + "deeper": {Reference: "a.refAnother"}, "docs": {Type: "string", Description: "This has some documentation!", Required: []string{"docs"}, Enum: []string{"one", "two", "three", "four", "five", "six", "seven"}, diff --git a/docparse/testdata/src/a/a.go b/docparse/testdata/src/a/a.go index 99feb59..15b9af5 100644 --- a/docparse/testdata/src/a/a.go +++ b/docparse/testdata/src/a/a.go @@ -27,6 +27,7 @@ type foo struct { pkg mail.Address pkgSlice []mail.Address pkgSliceP []*mail.Address + cSlice []customStr deeper refAnother // This has some documentation! {required}