Add more controls to ContentUnit (#75)

* Add default response support to content unit

* Add ContentUnitPreparer

* Add ContentUnit options

* Add more tests, fix description and no content handling

Author: vearutop

internal/operation_context.go

@@ -75,7 +75,12 @@ func (o *OperationContext) SetPathPattern(pattern string) {
 // AddReqStructure adds request content schema.
 func (o *OperationContext) AddReqStructure(s interface{}, options ...openapi.ContentOption) {
 	c := openapi.ContentUnit{}
-	c.Structure = s
+
+	if cp, ok := s.(openapi.ContentUnitPreparer); ok {
+		cp.SetupContentUnit(&c)
+	} else {
+		c.Structure = s
+	}
 
 	for _, o := range options {
 		o(&c)
@@ -87,7 +92,12 @@ func (o *OperationContext) AddReqStructure(s interface{}, options ...openapi.Con
 // AddRespStructure adds response content schema.
 func (o *OperationContext) AddRespStructure(s interface{}, options ...openapi.ContentOption) {
 	c := openapi.ContentUnit{}
-	c.Structure = s
+
+	if cp, ok := s.(openapi.ContentUnitPreparer); ok {
+		cp.SetupContentUnit(&c)
+	} else {
+		c.Structure = s
+	}
 
 	for _, o := range options {
 		o(&c)

openapi3/_testdata/openapi_req.json

@@ -16,7 +16,7 @@
      {"name":"in_cookie","in":"cookie","deprecated":true,"schema":{"type":"string","deprecated":true}},
      {"name":"in_header","in":"header","schema":{"type":"number"}}
     ],
-    "requestBody":{"content":{"text/csv":{"schema":{"type":"string"}}}},
+    "requestBody":{"description":"Request body in CSV format.","content":{"text/csv":{"schema":{"type":"string"}}}},
     "responses":{"204":{"description":"No Content"}}
    }
   }

openapi3/helper.go

@@ -106,7 +106,7 @@ func (s *Spec) AddOperation(method, path string, operation Operation) error {
 	}
 
 	// Add "No Content" response if there are no responses configured.
-	if len(operation.Responses.MapOfResponseOrRefValues) == 0 {
+	if len(operation.Responses.MapOfResponseOrRefValues) == 0 && operation.Responses.Default == nil {
 		operation.Responses.WithMapOfResponseOrRefValuesItem(strconv.Itoa(http.StatusNoContent), ResponseOrRef{
 			Response: &Response{
 				Description: http.StatusText(http.StatusNoContent),

openapi3/reflect.go

@@ -267,6 +267,10 @@ func (r *Reflector) setupRequest(o *Operation, oc openapi.OperationContext) erro
 		default:
 			r.stringRequestBody(o, cu.ContentType, cu.Format)
 		}
+
+		if cu.Description != "" && o.RequestBody != nil && o.RequestBody.RequestBody != nil {
+			o.RequestBody.RequestBody.WithDescription(cu.Description)
+		}
 	}
 
 	return nil
@@ -690,15 +694,29 @@ func (r *Reflector) hasJSONBody(output interface{}) (bool, error) {
 
 func (r *Reflector) setupResponse(o *Operation, oc openapi.OperationContext) error {
 	for _, cu := range oc.Response() {
-		if cu.HTTPStatus == 0 {
-			cu.HTTPStatus = 200
+		if cu.HTTPStatus == 0 && !cu.IsDefault {
+			cu.HTTPStatus = http.StatusOK
 		}
 
 		cu.ContentType = strings.Split(cu.ContentType, ";")[0]
 
 		httpStatus := strconv.Itoa(cu.HTTPStatus)
 		resp := o.Responses.MapOfResponseOrRefValues[httpStatus].Response
 
+		switch {
+		case cu.IsDefault:
+			httpStatus = "default"
+
+			if o.Responses.Default == nil {
+				o.Responses.Default = &ResponseOrRef{}
+			}
+
+			resp = o.Responses.Default.Response
+		case cu.HTTPStatus > 0 && cu.HTTPStatus < 6:
+			httpStatus = strconv.Itoa(cu.HTTPStatus) + "XX"
+			resp = o.Responses.MapOfResponseOrRefValues[httpStatus].Response
+		}
+
 		if resp == nil {
 			resp = &Response{}
 		}
@@ -721,13 +739,19 @@ func (r *Reflector) setupResponse(o *Operation, oc openapi.OperationContext) err
 			}
 		}
 
+		if cu.Description != "" {
+			resp.Description = cu.Description
+		}
+
 		if resp.Description == "" {
 			resp.Description = http.StatusText(cu.HTTPStatus)
 		}
 
-		o.Responses.WithMapOfResponseOrRefValuesItem(httpStatus, ResponseOrRef{
-			Response: resp,
-		})
+		if cu.IsDefault {
+			o.Responses.Default = &ResponseOrRef{Response: resp}
+		} else {
+			o.Responses.WithMapOfResponseOrRefValuesItem(httpStatus, ResponseOrRef{Response: resp})
+		}
 	}
 
 	return nil

openapi3/reflect_test.go

@@ -989,3 +989,42 @@ func TestReflector_AddOperation_request_queryObject_deepObject(t *testing.T) {
 	  }
 	}`, reflector.Spec)
 }
+
+type textCSV struct{}
+
+func (t textCSV) SetupContentUnit(cu *openapi.ContentUnit) {
+	cu.ContentType = "text/csv"
+	cu.Description = "This is CSV."
+	cu.IsDefault = true
+}
+
+func TestReflector_AddOperation_contentUnitPreparer(t *testing.T) {
+	r := openapi3.NewReflector()
+	oc, err := r.NewOperationContext(http.MethodPost, "/foo")
+	require.NoError(t, err)
+
+	oc.AddReqStructure(textCSV{})
+	oc.AddRespStructure(textCSV{})
+
+	require.NoError(t, r.AddOperation(oc))
+
+	assertjson.EqMarshal(t, `{
+	  "openapi":"3.0.3","info":{"title":"","version":""},
+	  "paths":{
+		"/foo":{
+		  "post":{
+			"requestBody":{
+			  "description":"This is CSV.",
+			  "content":{"text/csv":{"schema":{"type":"string"}}}
+			},
+			"responses":{
+			  "default":{
+				"description":"This is CSV.",
+				"content":{"text/csv":{"schema":{"type":"string"}}}
+			  }
+			}
+		  }
+		}
+	  }
+	}`, r.SpecSchema())
+}

operation.go

@@ -27,14 +27,39 @@ type ContentOption func(cu *ContentUnit)
 
 // ContentUnit defines HTTP content.
 type ContentUnit struct {
-	Structure    interface{}
-	ContentType  string
-	Format       string
-	HTTPStatus   int
+	Structure   interface{}
+	ContentType string
+	Format      string
+
+	// HTTPStatus can have values 100-599 for single status, or 1-5 for status families (e.g. 2XX)
+	HTTPStatus int
+
+	// IsDefault indicates default response.
+	IsDefault bool
+
 	Description  string
 	fieldMapping map[In]map[string]string
 }
 
+// ContentUnitPreparer defines self-contained ContentUnit.
+type ContentUnitPreparer interface {
+	SetupContentUnit(cu *ContentUnit)
+}
+
+// WithContentType is a ContentUnit option.
+func WithContentType(contentType string) func(cu *ContentUnit) {
+	return func(cu *ContentUnit) {
+		cu.ContentType = contentType
+	}
+}
+
+// WithHTTPStatus is a ContentUnit option.
+func WithHTTPStatus(httpStatus int) func(cu *ContentUnit) {
+	return func(cu *ContentUnit) {
+		cu.HTTPStatus = httpStatus
+	}
+}
+
 // SetFieldMapping sets custom field mapping.
 func (c *ContentUnit) SetFieldMapping(in In, fieldToParamName map[string]string) {
 	if len(fieldToParamName) == 0 {

operation_test.go

@@ -0,0 +1,18 @@
+package openapi_test
+
+import (
+	"net/http"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/swaggest/openapi-go"
+)
+
+func TestContentUnit_options(t *testing.T) {
+	cu := openapi.ContentUnit{}
+	openapi.WithContentType("text/csv")(&cu)
+	openapi.WithHTTPStatus(http.StatusConflict)(&cu)
+
+	assert.Equal(t, "text/csv", cu.ContentType)
+	assert.Equal(t, http.StatusConflict, cu.HTTPStatus)
+}