docs: make max-depth expand parameter required (#755)

internal/e2e/sdk_client_test.go

@@ -213,7 +213,7 @@ func (c *sdkClient) expand(t require.TestingT, r *relationtuple.SubjectSet, dept
 			WithNamespace(r.Namespace).
 			WithObject(r.Object).
 			WithRelation(r.Relation).
-			WithMaxDepth(pointerx.Int64(int64(depth))),
+			WithMaxDepth(int64(depth)),
 	)
 	require.NoError(t, err)
 	return buildTree(t, resp.Payload)

internal/expand/handler.go

@@ -53,6 +53,7 @@ func (h *handler) RegisterWriteGRPC(s *grpc.Server) {}
 // nolint:deadcode,unused
 type getExpandRequest struct {
 	// in:query
+	// required: true
 	MaxDepth int `json:"max-depth"`
 }
 
@@ -76,6 +77,10 @@ type getExpandRequest struct {
 //       404: genericError
 //       500: genericError
 func (h *handler) getExpand(w http.ResponseWriter, r *http.Request, _ httprouter.Params) {
+	if !r.URL.Query().Has("max-depth") {
+		h.d.Writer().WriteError(w, r, herodot.ErrBadRequest.WithError("required query parameter 'max-depth' is missing"))
+		return
+	}
 	depth, err := strconv.ParseInt(r.URL.Query().Get("max-depth"), 0, 0)
 	if err != nil {
 		h.d.Writer().WriteError(w, r, herodot.ErrBadRequest.WithError(err.Error()))

internal/expand/handler_test.go

@@ -35,6 +35,16 @@ func TestRESTHandler(t *testing.T) {
 	ts := httptest.NewServer(r)
 	defer ts.Close()
 
+	t.Run("case=returns required query parameter max-depth is missing is missing", func(t *testing.T) {
+		resp, err := ts.Client().Get(ts.URL + expand.RouteBase)
+		require.NoError(t, err)
+
+		assert.Equal(t, http.StatusBadRequest, resp.StatusCode)
+		body, err := io.ReadAll(resp.Body)
+		require.NoError(t, err)
+		assert.Contains(t, string(body), "required query parameter 'max-depth'")
+	})
+
 	t.Run("case=returns bad request on malformed int", func(t *testing.T) {
 		resp, err := ts.Client().Get(ts.URL + expand.RouteBase + "?max-depth=foo")
 		require.NoError(t, err)

spec/api.json

@@ -316,7 +316,8 @@
             "type": "integer",
             "format": "int64",
             "name": "max-depth",
-            "in": "query"
+            "in": "query",
+            "required": true
           }
         ],
         "responses": {