fix: Adjust OpenAPI index POST example request body (#3268)

## Relevant issue(s)

Resolves #2459

## Description

On the OpenAPI tool of the playground, the Index POST tab contained an
example body that was incorrect. It listed ID as a field which could be
set, which was untrue (this value is automatically generated, and trying
to pass one in throws an error.) To adjust this, I have created a new
description structure called `IndexCreateRequestDescription` which is
meant to be used for this type of HTTP request. To go alongside this
change, a new schema type, `indexCreateRequestSchema` was also created.

## Tasks

- [x] I made sure the code is well commented, particularly
hard-to-understand areas.
- [x] I made sure the repository-held documentation is changed
accordingly.
- [x] I made sure the pull request title adheres to the conventional
commit style (the subset used in the project can be found in
[tools/configs/chglog/config.yml](tools/configs/chglog/config.yml)).


## How has this been tested?

The platform(s) on which this was tested:
- Windows

cli/index_create.go

@@ -69,7 +69,7 @@ Example: create a unique index for 'Users' collection on 'name' in ascending ord
 				})
 			}
 
-			desc := client.IndexDescription{
+			desc := client.IndexDescriptionCreateRequest{
 				Name:   nameArg,
 				Fields: fields,
 				Unique: uniqueArg,
@@ -79,11 +79,11 @@ Example: create a unique index for 'Users' collection on 'name' in ascending ord
 				return err
 			}
 
-			desc, err = col.CreateIndex(cmd.Context(), desc)
+			descWithID, err := col.CreateIndex(cmd.Context(), desc)
 			if err != nil {
 				return err
 			}
-			return writeJSON(cmd, desc)
+			return writeJSON(cmd, descWithID)
 		},
 	}
 	cmd.Flags().StringVarP(&collectionArg, "collection", "c", "", "Collection name")

client/collection.go

@@ -115,7 +115,7 @@ type Collection interface {
 	// only contain letters, numbers, and underscores.
 	// If the name of the index is not provided, it will be generated.
 	// WARNING: This method can not create index for a collection that has a policy.
-	CreateIndex(context.Context, IndexDescription) (IndexDescription, error)
+	CreateIndex(context.Context, IndexDescriptionCreateRequest) (IndexDescription, error)
 
 	// DropIndex drops an index from the collection.
 	DropIndex(ctx context.Context, indexName string) error

client/index.go

@@ -36,6 +36,18 @@ type IndexDescription struct {
 	Unique bool
 }
 
+// IndexDescriptionCreateRequest describes an index creation request.
+// It does not contain the ID, as it is not a valid field for the request body.
+// Instead it should be automatically generated.
+type IndexDescriptionCreateRequest struct {
+	// Name contains the name of the index.
+	Name string
+	// Fields contains the fields that are being indexed.
+	Fields []IndexedFieldDescription
+	// Unique indicates whether the index is unique.
+	Unique bool
+}
+
 // CollectionIndex is an interface for indexing documents in a collection.
 type CollectionIndex interface {
 	// Save indexes a document by storing indexed field values.

docs/website/references/http/openapi.json

@@ -442,6 +442,31 @@
                 },
                 "type": "object"
             },
+            "index_create_request": {
+                "properties": {
+                    "Fields": {
+                        "items": {
+                            "properties": {
+                                "Descending": {
+                                    "type": "boolean"
+                                },
+                                "Name": {
+                                    "type": "string"
+                                }
+                            },
+                            "type": "object"
+                        },
+                        "type": "array"
+                    },
+                    "Name": {
+                        "type": "string"
+                    },
+                    "Unique": {
+                        "type": "boolean"
+                    }
+                },
+                "type": "object"
+            },
             "lens_config": {
                 "properties": {
                     "DestinationSchemaVersionID": {
@@ -1245,7 +1270,7 @@
                     "content": {
                         "application/json": {
                             "schema": {
-                                "$ref": "#/components/schemas/index"
+                                "$ref": "#/components/schemas/index_create_request"
                             }
                         }
                     },

http/client_collection.go

@@ -379,7 +379,7 @@ func (c *Collection) GetAllDocIDs(
 
 func (c *Collection) CreateIndex(
 	ctx context.Context,
-	indexDesc client.IndexDescription,
+	indexDesc client.IndexDescriptionCreateRequest,
 ) (client.IndexDescription, error) {
 	if !c.Description().Name.HasValue() {
 		return client.IndexDescription{}, client.ErrOperationNotPermittedOnNamelessCols

http/handler_collection.go

@@ -259,7 +259,12 @@ func (s *collectionHandler) CreateIndex(rw http.ResponseWriter, req *http.Reques
 		responseJSON(rw, http.StatusBadRequest, errorResponse{err})
 		return
 	}
-	index, err := col.CreateIndex(req.Context(), indexDesc)
+	descWithoutID := client.IndexDescriptionCreateRequest{
+		Name:   indexDesc.Name,
+		Fields: indexDesc.Fields,
+		Unique: indexDesc.Unique,
+	}
+	index, err := col.CreateIndex(req.Context(), descWithoutID)
 	if err != nil {
 		responseJSON(rw, http.StatusBadRequest, errorResponse{err})
 		return
@@ -318,6 +323,9 @@ func (h *collectionHandler) bindRoutes(router *Router) {
 	indexSchema := &openapi3.SchemaRef{
 		Ref: "#/components/schemas/index",
 	}
+	indexCreateRequestSchema := &openapi3.SchemaRef{
+		Ref: "#/components/schemas/index_create_request",
+	}
 
 	collectionNamePathParam := openapi3.NewPathParameter("name").
 		WithDescription("Collection name").
@@ -389,7 +397,7 @@ func (h *collectionHandler) bindRoutes(router *Router) {
 
 	createIndexRequest := openapi3.NewRequestBody().
 		WithRequired(true).
-		WithContent(openapi3.NewContentWithJSONSchemaRef(indexSchema))
+		WithContent(openapi3.NewContentWithJSONSchemaRef(indexCreateRequestSchema))
 	createIndexResponse := openapi3.NewResponse().
 		WithDescription("Index description").
 		WithJSONSchemaRef(indexSchema)

http/openapi.go

@@ -32,6 +32,7 @@ var openApiSchemas = map[string]any{
 	"schema":                          &client.SchemaDescription{},
 	"collection_definition":           &client.CollectionDefinition{},
 	"index":                           &client.IndexDescription{},
+	"index_create_request":            &client.IndexDescriptionCreateRequest{},
 	"delete_result":                   &client.DeleteResult{},
 	"update_result":                   &client.UpdateResult{},
 	"lens_config":                     &client.LensConfig{},

internal/db/collection_define.go

@@ -91,7 +91,12 @@ func (db *db) createCollections(
 		col := db.newCollection(desc, def.Schema)
 
 		for _, index := range desc.Indexes {
-			if _, err := col.createIndex(ctx, index); err != nil {
+			descWithoutID := client.IndexDescriptionCreateRequest{
+				Name:   index.Name,
+				Fields: index.Fields,
+				Unique: index.Unique,
+			}
+			if _, err := col.createIndex(ctx, descWithoutID); err != nil {
 				return nil, err
 			}
 		}

internal/db/collection_index.go

@@ -35,7 +35,7 @@ import (
 func (db *db) createCollectionIndex(
 	ctx context.Context,
 	collectionName string,
-	desc client.IndexDescription,
+	desc client.IndexDescriptionCreateRequest,
 ) (client.IndexDescription, error) {
 	col, err := db.getCollectionByName(ctx, collectionName)
 	if err != nil {
@@ -218,7 +218,7 @@ func (c *collection) deleteIndexedDocWithID(
 // the documents will be indexed by the new index.
 func (c *collection) CreateIndex(
 	ctx context.Context,
-	desc client.IndexDescription,
+	desc client.IndexDescriptionCreateRequest,
 ) (client.IndexDescription, error) {
 	ctx, txn, err := ensureContextTxn(ctx, c.db, false)
 	if err != nil {
@@ -235,7 +235,7 @@ func (c *collection) CreateIndex(
 
 func (c *collection) createIndex(
 	ctx context.Context,
-	desc client.IndexDescription,
+	desc client.IndexDescriptionCreateRequest,
 ) (CollectionIndex, error) {
 	if desc.Name != "" && !schema.IsValidIndexName(desc.Name) {
 		return nil, schema.NewErrIndexWithInvalidName("!")
@@ -266,9 +266,15 @@ func (c *collection) createIndex(
 	if err != nil {
 		return nil, err
 	}
-	desc.ID = uint32(colID)
 
-	buf, err := json.Marshal(desc)
+	descWithID := client.IndexDescription{
+		Name:   desc.Name,
+		ID:     uint32(colID),
+		Fields: desc.Fields,
+		Unique: desc.Unique,
+	}
+
+	buf, err := json.Marshal(descWithID)
 	if err != nil {
 		return nil, err
 	}
@@ -278,7 +284,7 @@ func (c *collection) createIndex(
 	if err != nil {
 		return nil, err
 	}
-	colIndex, err := NewCollectionIndex(c, desc)
+	colIndex, err := NewCollectionIndex(c, descWithID)
 	if err != nil {
 		return nil, err
 	}
@@ -491,7 +497,7 @@ func (c *collection) checkExistingFieldsAndAdjustRelFieldNames(
 
 func (c *collection) generateIndexNameIfNeededAndCreateKey(
 	ctx context.Context,
-	desc *client.IndexDescription,
+	desc *client.IndexDescriptionCreateRequest,
 ) (keys.CollectionIndexKey, error) {
 	// callers of this function must set a context transaction
 	txn := mustGetContextTxn(ctx)
@@ -524,10 +530,7 @@ func (c *collection) generateIndexNameIfNeededAndCreateKey(
 	return indexKey, nil
 }
 
-func validateIndexDescription(desc client.IndexDescription) error {
-	if desc.ID != 0 {
-		return NewErrNonZeroIndexIDProvided(desc.ID)
-	}
+func validateIndexDescription(desc client.IndexDescriptionCreateRequest) error {
 	if len(desc.Fields) == 0 {
 		return ErrIndexMissingFields
 	}