allow multiple samples for Write, issue #514 (#515)

* allow multiple samples for Write, issue #514

* update changelog

* chore: example handling request parameters with httpin (#518)

* use path package to join slash fragments #519 (#520)

* update hist

* update example openapi to use 3.10.1

* Add test for client request with and without trailing slash. (#522)

* Add test for client request with and without trailing slash.

* Correction.

* introduce MergePathStrategy

* Revert "introduce MergePathStrategy"

This reverts commit 709cf80.

* introduce MergePathStrategy for #521 #519 (#523)

* introduce MergePathStrategy for #521 #519

* update readme, set default to new strategy, add extra test

* link to security issue

* update change hist

* add hello world with TrimSlashStrategy

* two route example

* examples to show differences #519

* more route examples #519

* add examples for issue519 with path in root

* remove obsolete swagger example

* Update README.md

remover swagger12 mention

* allow multiple samples for Write, issue #514

---------

Co-authored-by: Ggicci <ggicci.t@gmail.com>
Co-authored-by: Gerrit <Gerrit91@users.noreply.github.com>

route.go

@@ -40,7 +40,8 @@ type Route struct {
 	ParameterDocs           []*Parameter
 	ResponseErrors          map[int]ResponseError
 	DefaultResponse         *ResponseError
-	ReadSample, WriteSample interface{} // structs that model an example request or response payload
+	ReadSample, WriteSample interface{}   // structs that model an example request or response payload
+	WriteSamples            []interface{} // if more than one return types is possible (oneof) then this will contain multiple values
 
 	// Extra information used to store custom information about the route.
 	Metadata map[string]interface{}

route_builder.go

@@ -31,17 +31,18 @@ type RouteBuilder struct {
 	typeNameHandleFunc TypeNameHandleFunction // required
 
 	// documentation
-	doc                     string
-	notes                   string
-	operation               string
-	readSample, writeSample interface{}
-	parameters              []*Parameter
-	errorMap                map[int]ResponseError
-	defaultResponse         *ResponseError
-	metadata                map[string]interface{}
-	extensions              map[string]interface{}
-	deprecated              bool
-	contentEncodingEnabled  *bool
+	doc                    string
+	notes                  string
+	operation              string
+	readSample             interface{}
+	writeSamples           []interface{}
+	parameters             []*Parameter
+	errorMap               map[int]ResponseError
+	defaultResponse        *ResponseError
+	metadata               map[string]interface{}
+	extensions             map[string]interface{}
+	deprecated             bool
+	contentEncodingEnabled *bool
 }
 
 // Do evaluates each argument with the RouteBuilder itself.
@@ -135,9 +136,9 @@ func (b RouteBuilder) ParameterNamed(name string) (p *Parameter) {
 	return p
 }
 
-// Writes tells what resource type will be written as the response payload. Optional.
-func (b *RouteBuilder) Writes(sample interface{}) *RouteBuilder {
-	b.writeSample = sample
+// Writes tells which one of the resource types will be written as the response payload. Optional.
+func (b *RouteBuilder) Writes(samples ...interface{}) *RouteBuilder {
+	b.writeSamples = samples // oneof
 	return b
 }
 
@@ -342,12 +343,16 @@ func (b *RouteBuilder) Build() Route {
 		ResponseErrors:                   b.errorMap,
 		DefaultResponse:                  b.defaultResponse,
 		ReadSample:                       b.readSample,
-		WriteSample:                      b.writeSample,
+		WriteSamples:                     b.writeSamples,
 		Metadata:                         b.metadata,
 		Deprecated:                       b.deprecated,
 		contentEncodingEnabled:           b.contentEncodingEnabled,
 		allowedMethodsWithoutContentType: b.allowedMethodsWithoutContentType,
 	}
+	// set WriteSample if one specified
+	if len(b.writeSamples) == 1 {
+		route.WriteSample = b.writeSamples[0]
+	}
 	route.Extensions = b.extensions
 	route.postBuild()
 	return route

route_builder_test.go

@@ -5,6 +5,35 @@ import (
 	"time"
 )
 
+func TestRouteBuilderWrites(t *testing.T) {
+	b := new(RouteBuilder)
+	b.To(dummy)
+	type StructA struct{}
+	type StructB struct{}
+	b.Writes(StructA{})
+	if got, want := len(b.writeSamples), 1; got != want {
+		t.Errorf("got [%v:%T] want [%v:%T]", got, got, want, want)
+	}
+	{
+		r := b.Build()
+		var null interface{}
+		if r.WriteSample == null {
+			t.Fail()
+		}
+	}
+	b.Writes(StructA{}, StructB{})
+	if got, want := len(b.writeSamples), 2; got != want {
+		t.Errorf("got [%v:%T] want [%v:%T]", got, got, want, want)
+	}
+	{
+		r := b.Build()
+		var null interface{}
+		if got, want := r.WriteSample, null; got != want {
+			t.Errorf("got [%v:%T] want [%v:%T]", got, got, want, want)
+		}
+	}
+}
+
 func TestRouteBuilder_PathParameter(t *testing.T) {
 	p := &Parameter{&ParameterData{Name: "name", Description: "desc"}}
 	p.AllowMultiple(true)