feat(CREATE): add openapi for /collections/{collectionId}/items POST

* openapi.go: add paramFeatureID, FeatureSchema, getFeatureExample()

Author: benoitdm-oslandia

internal/api/net.go

@@ -44,6 +44,9 @@ const (
 	// ContentTypeHTML
 	ContentTypeOpenAPI = "application/vnd.oai.openapi+json;version=3.0"
 
+	// ContentTypeAny
+	ContentTypeAny = "*/*"
+
 	// FormatJSON code and extension for JSON
 	FormatJSON = "json"
 
@@ -61,6 +64,9 @@ const (
 
 	// FormatXML code and extension for XML/GML
 	FormatXML = "xml"
+
+	// FormatAny code and extension for */*
+	FormatAny = "any"
 )
 
 // RequestedFormat gets the format for a request from extension or headers
@@ -85,6 +91,9 @@ func RequestedFormat(r *http.Request) string {
 	if strings.Contains(hdrAccept, ContentTypeSchemaJSON) {
 		return FormatSchemaJSON
 	}
+	if strings.Contains(hdrAccept, ContentTypeAny) {
+		return FormatAny
+	}
 	if strings.Contains(hdrAccept, ContentTypeHTML) {
 		return FormatHTML
 	}

internal/api/openapi.go

@@ -14,13 +14,80 @@ package api
 */
 
 import (
+	"encoding/json"
 	"net/url"
 
 	"github.com/CrunchyData/pg_featureserv/internal/conf"
 	"github.com/getkin/kin-openapi/openapi3"
 	log "github.com/sirupsen/logrus"
 )
 
+func getFeatureExample() map[string]interface{} {
+	var result map[string]interface{}
+	var jsonStr = `{"type":"Feature","geometry":{"type":"Point","coordinates":[-70.88461956597838,47.807897059236495]},"properties":{"prop_a":"propA","prop_b":1,"prop_c":"propC","prop_d":1}}`
+	err := json.Unmarshal([]byte(jsonStr), &result)
+	if err != nil {
+		return nil
+	}
+	return result
+}
+
+var FeatureSchema openapi3.Schema = openapi3.Schema{
+	Type:     "object",
+	Required: []string{},
+	Properties: map[string]*openapi3.SchemaRef{
+		"id": {
+			Value: &openapi3.Schema{
+				OneOf: []*openapi3.SchemaRef{
+					openapi3.NewSchemaRef("", &openapi3.Schema{
+						Type: "number", Format: "long",
+					}),
+					openapi3.NewSchemaRef("", &openapi3.Schema{
+						Type: "string",
+					}),
+				},
+			},
+		},
+		"type": {
+			Value: &openapi3.Schema{
+				Type:    "string",
+				Default: "Feature",
+			},
+		},
+		"geometry": {
+			Value: &openapi3.Schema{
+				Items: &openapi3.SchemaRef{
+					Value: &openapi3.Schema{
+						Type: "string", // mandatory to validate the schema
+						OneOf: []*openapi3.SchemaRef{
+							openapi3.NewSchemaRef("https://geojson.org/schema/Point.json", &openapi3.Schema{Type: "string"}),
+							openapi3.NewSchemaRef("https://geojson.org/schema/LineString.json", &openapi3.Schema{Type: "string"}),
+							openapi3.NewSchemaRef("https://geojson.org/schema/Polygon.json", &openapi3.Schema{Type: "string"}),
+							openapi3.NewSchemaRef("https://geojson.org/schema/MultiPoint.json", &openapi3.Schema{Type: "string"}),
+							openapi3.NewSchemaRef("https://geojson.org/schema/MultiLineString.json", &openapi3.Schema{Type: "string"}),
+							openapi3.NewSchemaRef("https://geojson.org/schema/MultiPolygon.json", &openapi3.Schema{Type: "string"}),
+						},
+					},
+				},
+			},
+		},
+		"properties": {
+			Value: &openapi3.Schema{
+				Type: "object",
+			},
+		},
+		"bbox": {
+			Value: &openapi3.Schema{
+				Type:     "array",
+				MinItems: 4,
+				MaxItems: openapi3.Uint64Ptr(4),
+				Items:    openapi3.NewSchemaRef("", openapi3.NewFloat64Schema().WithMin(-180).WithMax(180)),
+			},
+		},
+	},
+	Example: getFeatureExample(),
+}
+
 // GetOpenAPIContent returns a Swagger OpenAPI structure
 func GetOpenAPIContent(urlBase string) *openapi3.Swagger {
 
@@ -53,6 +120,16 @@ func GetOpenAPIContent(urlBase string) *openapi3.Swagger {
 			AllowEmptyValue: false,
 		},
 	}
+	paramFeatureID := openapi3.ParameterRef{
+		Value: &openapi3.Parameter{
+			Name:            "featureId",
+			Description:     "Id of feature in collection to retrieve data for.",
+			In:              "path",
+			Required:        true,
+			Schema:          &openapi3.SchemaRef{Value: openapi3.NewStringSchema()},
+			AllowEmptyValue: false,
+		},
+	}
 	paramBbox := openapi3.ParameterRef{
 		Value: &openapi3.Parameter{
 			Name:        "bbox",
@@ -216,7 +293,7 @@ func GetOpenAPIContent(urlBase string) *openapi3.Swagger {
 			Name:            "type",
 			Description:     "Data schema type (create, update, etc.).",
 			In:              "query",
-			Required:        false,
+			Required:        true,
 			Schema:          &openapi3.SchemaRef{Value: openapi3.NewStringSchema()},
 			AllowEmptyValue: false,
 		},
@@ -365,6 +442,35 @@ func GetOpenAPIContent(urlBase string) *openapi3.Swagger {
 						},
 					},
 				},
+				Post: &openapi3.Operation{
+					OperationID: "createCollectionFeature",
+					Parameters: openapi3.Parameters{
+						&paramCollectionID,
+						// TODO keep it for the next evolution
+						// &paramCrs,
+					},
+					RequestBody: &openapi3.RequestBodyRef{
+						Value: &openapi3.RequestBody{
+							Description: "Add a new feature",
+							Required:    true,
+							Content:     openapi3.NewContentWithJSONSchema(&FeatureSchema),
+						},
+					},
+					Responses: openapi3.Responses{
+						"201": &openapi3.ResponseRef{
+							Value: &openapi3.Response{
+								Description: "Empty body with location header",
+								Headers: map[string]*openapi3.HeaderRef{
+									"location": {
+										Value: &openapi3.Header{
+											Description: "Contains a link to access to the new feature data",
+										},
+									},
+								},
+							},
+						},
+					},
+				},
 			},
 			apiBase + "collections/{collectionId}/schema": &openapi3.PathItem{
 				Summary:     "Feature schema for collection",
@@ -374,6 +480,16 @@ func GetOpenAPIContent(urlBase string) *openapi3.Swagger {
 					Parameters: openapi3.Parameters{
 						&paramCollectionID,
 						&paramType,
+						&openapi3.ParameterRef{
+							Value: &openapi3.Parameter{
+								Name:            "accept",
+								Description:     "Only accept application/schema+schema",
+								In:              "header",
+								Required:        true,
+								Schema:          &openapi3.SchemaRef{Value: openapi3.NewStringSchema()},
+								AllowEmptyValue: false,
+							},
+						},
 					},
 					Responses: openapi3.Responses{
 						"200": &openapi3.ResponseRef{
@@ -399,16 +515,7 @@ func GetOpenAPIContent(urlBase string) *openapi3.Swagger {
 					OperationID: "getCollectionFeature",
 					Parameters: openapi3.Parameters{
 						&paramCollectionID,
-						&openapi3.ParameterRef{
-							Value: &openapi3.Parameter{
-								Name:            "featureId",
-								Description:     "Id of feature in collection to retrieve data for.",
-								In:              "path",
-								Required:        true,
-								Schema:          &openapi3.SchemaRef{Value: openapi3.NewStringSchema()},
-								AllowEmptyValue: false,
-							},
-						},
+						&paramFeatureID,
 						&paramProperties,
 						&paramTransform,
 						&paramCrs,

internal/service/handler.go

@@ -286,7 +286,9 @@ func handleCollectionSchemas(w http.ResponseWriter, r *http.Request) *appError {
 
 	ctx := r.Context()
 	switch format {
-	case api.FormatSchemaJSON:
+	case api.FormatSchemaJSON,
+		// workaround to have swagger working:
+		api.FormatAny:
 		{
 			switch schemaType {
 			case "create":

internal/service/handler_post_test.go

@@ -42,11 +42,23 @@ func TestApiContainsCollectionSchemas(t *testing.T) {
 	util.Assert(t, path != nil, "schema path exists")
 	util.Equals(t, "Provides access to data representation (schema) for any features in specified collection", path.Description, "schema path present")
 	util.Equals(t, "getCollectionSchema", path.Get.OperationID, "schema path get present")
-	util.Equals(t, 2, len(path.Get.Parameters), "schema path get present")
+	util.Equals(t, 2, len(path.Get.Parameters), "# path")
 	util.Assert(t, path.Get.Parameters.GetByInAndName("path", "collectionId") != nil, "collectionId path parameter exists")
 	util.Assert(t, path.Get.Parameters.GetByInAndName("query", "type") != nil, "type query parameter exists")
 }
 
+// checks swagger api contains method PATCH for updating a feaure from a specified collection
+func TestApiContainsMethodPostFeature(t *testing.T) {
+	resp := hTest.DoRequest(t, "/api")
+	body, _ := ioutil.ReadAll(resp.Body)
+
+	var v openapi3.Swagger
+	err := json.Unmarshal(body, &v)
+	util.Assert(t, err == nil, fmt.Sprintf("%v", err))
+
+	util.Equals(t, "createCollectionFeature", v.Paths.Find("/collections/{collectionId}/items").Post.OperationID, "method POST present")
+}
+
 // checks collection schema contains valid data description
 func TestGetCollectionCreateSchema(t *testing.T) {
 	path := "/collections/mock_a/schema?type=create"