encoding/openapi: add Info and DescriptorFunc features
Two settings added to Generator:
- Info adds the OpenAPI info section.
- DescriptorFunc allows for custom descriptions, given
a value.
If the All API is used, an empty info section will be added
if the user hasn't given any. This is to reflect the fact
that info.version and info.title are required.
Issue #56
Change-Id: Ief29b40bf6be9c8026052588f6de9fb06d41095f
Reviewed-on: https://cue-review.googlesource.com/c/cue/+/2442
Reviewed-by: Marcel van Lohuizen <mpvl@golang.org>
diff --git a/encoding/openapi/build.go b/encoding/openapi/build.go
index 6b83e78..8224a71 100644
--- a/encoding/openapi/build.go
+++ b/encoding/openapi/build.go
@@ -35,6 +35,7 @@
expandRefs bool
nameFunc func(inst *cue.Instance, path []string) string
+ descFunc func(v cue.Value) string
schemas *OrderedMap
@@ -59,6 +60,7 @@
refPrefix: "components/schema",
expandRefs: g.ExpandReferences,
nameFunc: g.ReferenceFunc,
+ descFunc: g.DescriptionFunc,
schemas: &OrderedMap{},
externalRefs: map[string]*externalType{},
}
@@ -148,11 +150,17 @@
if !isRef {
doc := []string{}
- for _, d := range v.Doc() {
- doc = append(doc, d.Text())
+ if b.ctx.descFunc != nil {
+ if str := b.ctx.descFunc(v); str != "" {
+ doc = append(doc, str)
+ }
+ } else {
+ for _, d := range v.Doc() {
+ doc = append(doc, d.Text())
+ }
}
if len(doc) > 0 {
- str := strings.TrimSpace(strings.Join(doc, "\n"))
+ str := strings.TrimSpace(strings.Join(doc, "\n\n"))
schema.prepend("description", str)
}
}
diff --git a/encoding/openapi/openapi.go b/encoding/openapi/openapi.go
index 8d518a7..93a4036 100644
--- a/encoding/openapi/openapi.go
+++ b/encoding/openapi/openapi.go
@@ -22,10 +22,20 @@
// A Generator converts CUE to OpenAPI.
type Generator struct {
+ // Info specifies the info section of the OpenAPI document. To be a valid
+ // OpenAPI document, it must include at least the title and version fields.
+ Info OrderedMap
+
// ReferenceFunc allows users to specify an alternative representation
// for references.
ReferenceFunc func(inst *cue.Instance, path []string) string
+ // DescriptionFunc allows rewriting a description associated with a certain
+ // field. A typical implementation compiles the description from the
+ // comments obtains from the Doc method. No description field is added if
+ // the empty string is returned.
+ DescriptionFunc func(v cue.Value) string
+
// SelfContained causes all non-expanded external references to be included
// in this document.
SelfContained bool
@@ -68,6 +78,7 @@
top := OrderedMap{}
top.set("openapi", "3.0.0")
+ top.set("info", g.Info)
top.set("components", schemas)
return top, nil
diff --git a/encoding/openapi/openapi_test.go b/encoding/openapi/openapi_test.go
index e1fd2e3..6e41e2d 100644
--- a/encoding/openapi/openapi_test.go
+++ b/encoding/openapi/openapi_test.go
@@ -20,6 +20,7 @@
"flag"
"io/ioutil"
"path/filepath"
+ "strings"
"testing"
"cuelang.org/go/cue"
@@ -30,8 +31,9 @@
var update *bool = flag.Bool("update", false, "update the test output")
func TestParseDefinitions(t *testing.T) {
+ info := OrderedMap{KeyValue{"title", "test"}, KeyValue{"version", "v1"}}
defaultConfig := &Config{}
- resolveRefs := &Config{ExpandReferences: true}
+ resolveRefs := &Config{Info: info, ExpandReferences: true}
testCases := []struct {
in, out string
@@ -56,6 +58,18 @@
"openapi.cue",
"openapi-norefs.json",
resolveRefs,
+ }, {
+ "oneof.cue",
+ "oneof-funcs.json",
+ &Generator{
+ Info: info,
+ ReferenceFunc: func(inst *cue.Instance, path []string) string {
+ return strings.ToUpper(strings.Join(path, "_"))
+ },
+ DescriptionFunc: func(v cue.Value) string {
+ return "Randomly picked description from a set of size one."
+ },
+ },
}}
for _, tc := range testCases {
t.Run(tc.out, func(t *testing.T) {
diff --git a/encoding/openapi/testdata/array.json b/encoding/openapi/testdata/array.json
index 4b29400..88597a0 100644
--- a/encoding/openapi/testdata/array.json
+++ b/encoding/openapi/testdata/array.json
@@ -1,5 +1,6 @@
{
"openapi": "3.0.0",
+ "info": {},
"components": {
"schema": {
"Arrays": {
diff --git a/encoding/openapi/testdata/oneof-funcs.json b/encoding/openapi/testdata/oneof-funcs.json
new file mode 100644
index 0000000..2ca742f
--- /dev/null
+++ b/encoding/openapi/testdata/oneof-funcs.json
@@ -0,0 +1,70 @@
+{
+ "openapi": "3.0.0",
+ "info": {
+ "title": "test",
+ "version": "v1"
+ },
+ "components": {
+ "schema": {
+ "MYSTRING": {
+ "description": "Randomly picked description from a set of size one.",
+ "oneOf": [
+ {
+ "type": "object",
+ "required": [
+ "exact"
+ ],
+ "properties": {
+ "exact": {
+ "description": "Randomly picked description from a set of size one.",
+ "type": "string",
+ "format": "string"
+ }
+ }
+ },
+ {
+ "type": "object",
+ "required": [
+ "regex"
+ ],
+ "properties": {
+ "regex": {
+ "description": "Randomly picked description from a set of size one.",
+ "type": "string",
+ "format": "string"
+ }
+ }
+ }
+ ]
+ },
+ "MYINT": {
+ "description": "Randomly picked description from a set of size one.",
+ "type": "integer"
+ },
+ "FOO": {
+ "description": "Randomly picked description from a set of size one.",
+ "type": "object",
+ "required": [
+ "include",
+ "exclude",
+ "count"
+ ],
+ "properties": {
+ "count": {
+ "$ref": "#/components/schema/MYINT"
+ },
+ "exclude": {
+ "description": "Randomly picked description from a set of size one.",
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schema/MYSTRING"
+ }
+ },
+ "include": {
+ "$ref": "#/components/schema/MYSTRING"
+ }
+ }
+ }
+ }
+ }
+}
\ No newline at end of file
diff --git a/encoding/openapi/testdata/oneof.json b/encoding/openapi/testdata/oneof.json
index ce39ad4..83384fb 100644
--- a/encoding/openapi/testdata/oneof.json
+++ b/encoding/openapi/testdata/oneof.json
@@ -1,5 +1,6 @@
{
"openapi": "3.0.0",
+ "info": {},
"components": {
"schema": {
"MyString": {
diff --git a/encoding/openapi/testdata/openapi-norefs.json b/encoding/openapi/testdata/openapi-norefs.json
index 00803cd..d6f80b3 100644
--- a/encoding/openapi/testdata/openapi-norefs.json
+++ b/encoding/openapi/testdata/openapi-norefs.json
@@ -1,5 +1,9 @@
{
"openapi": "3.0.0",
+ "info": {
+ "title": "test",
+ "version": "v1"
+ },
"components": {
"schema": {
"MyMessage": {
diff --git a/encoding/openapi/testdata/openapi.json b/encoding/openapi/testdata/openapi.json
index c0ef7db..d4c6691 100644
--- a/encoding/openapi/testdata/openapi.json
+++ b/encoding/openapi/testdata/openapi.json
@@ -1,5 +1,6 @@
{
"openapi": "3.0.0",
+ "info": {},
"components": {
"schema": {
"MyMessage": {
diff --git a/encoding/openapi/testdata/simple.json b/encoding/openapi/testdata/simple.json
index 8110d69..ce7675e 100644
--- a/encoding/openapi/testdata/simple.json
+++ b/encoding/openapi/testdata/simple.json
@@ -1,5 +1,9 @@
{
"openapi": "3.0.0",
+ "info": {
+ "title": "test",
+ "version": "v1"
+ },
"components": {
"schema": {
"MyStruct": {
