feat: add slice command to filter OpenAPI specs

tools/cli/internal/cli/flag/flag.go

@@ -51,4 +51,7 @@ const (
 	StabilityLevelShort      = "l"
 	Version                  = "version"
 	VersionShort             = "v"
+	OperationIDs             = "ids"
+	Tags                     = "tags"
+	Paths                    = "paths"
 )

tools/cli/internal/cli/root/openapi/builder.go

@@ -22,6 +22,7 @@ import (
 	"github.com/mongodb/openapi/tools/cli/internal/cli/changelog"
 	"github.com/mongodb/openapi/tools/cli/internal/cli/filter"
 	"github.com/mongodb/openapi/tools/cli/internal/cli/merge"
+	"github.com/mongodb/openapi/tools/cli/internal/cli/slice"
 	"github.com/mongodb/openapi/tools/cli/internal/cli/split"
 	"github.com/mongodb/openapi/tools/cli/internal/cli/sunset"
 	"github.com/mongodb/openapi/tools/cli/internal/cli/versions"
@@ -63,6 +64,7 @@ func Builder() *cobra.Command {
 		breakingchanges.Builder(),
 		sunset.Builder(),
 		filter.Builder(),
+		slice.Builder(),
 	)
 	return rootCmd
 }

tools/cli/internal/cli/slice/slice.go

@@ -0,0 +1,141 @@
+// Copyright 2024 MongoDB Inc
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//	http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package slice
+
+import (
+	"errors"
+	"fmt"
+	"log"
+
+	"github.com/mongodb/openapi/tools/cli/internal/cli/flag"
+	"github.com/mongodb/openapi/tools/cli/internal/cli/usage"
+	"github.com/mongodb/openapi/tools/cli/internal/openapi"
+	"github.com/mongodb/openapi/tools/cli/internal/openapi/slice"
+	"github.com/spf13/afero"
+	"github.com/spf13/cobra"
+)
+
+type Opts struct {
+	fs           afero.Fs
+	basePath     string
+	outputPath   string
+	format       string
+	operationIDs []string
+	tags         []string
+	paths        []string
+}
+
+func (o *Opts) Run() error {
+	loader := openapi.NewOpenAPI3()
+	specInfo, err := loader.CreateOpenAPISpecFromPath(o.basePath)
+	if err != nil {
+		return err
+	}
+
+	criteria := &slice.Criteria{
+		OperationIDs: o.operationIDs,
+		Tags:         o.tags,
+		Paths:        o.paths,
+	}
+
+	// Log what we're slicing
+	if len(criteria.OperationIDs) > 0 {
+		log.Printf("Slicing operations by IDs: %v", criteria.OperationIDs)
+	}
+	if len(criteria.Tags) > 0 {
+		log.Printf("Slicing operations by tags: %v", criteria.Tags)
+	}
+	if len(criteria.Paths) > 0 {
+		log.Printf("Slicing operations by paths: %v", criteria.Paths)
+	}
+
+	// Slice the spec (includes automatic cleanup of unused tags and schemas)
+	if err := slice.Slice(specInfo.Spec, criteria); err != nil {
+		return err
+	}
+
+	// Validate the sliced spec
+	if err := specInfo.Spec.Validate(loader.Loader.Context); err != nil {
+		log.Printf("[WARN] Sliced OpenAPI document has validation warnings: %v", err)
+	}
+
+	return openapi.Save(o.outputPath, specInfo.Spec, o.format, o.fs)
+}
+
+func (o *Opts) PreRunE(_ []string) error {
+	if o.basePath == "" {
+		return fmt.Errorf("no OAS detected. Please, use the flag %s to include the base OAS", flag.Spec)
+	}
+
+	if len(o.operationIDs) == 0 && len(o.tags) == 0 && len(o.paths) == 0 {
+		return errors.New("at least one of --operation-ids, --tags, or --paths must be specified")
+	}
+
+	return openapi.ValidateFormatAndOutput(o.format, o.outputPath)
+}
+
+// Builder builds the slice command with the following signature:
+// slice -s spec -o output.json --operation-ids "op1,op2" --tags "tag1,tag2" --paths "/api/v1".
+func Builder() *cobra.Command {
+	opts := &Opts{
+		fs: afero.NewOsFs(),
+	}
+
+	cmd := &cobra.Command{
+		Use:   "slice -s spec",
+		Short: "Slice a subset of an OpenAPI specification by operation IDs, tags, or paths",
+		Long: `Slice creates a valid mini OpenAPI specification containing only the operations
+that match the specified criteria. The output includes all necessary schemas and
+components referenced by the selected operations.
+
+You can filter by:
+  - Operation IDs: Specific operation identifiers
+  - Tags: Operations tagged with specific values
+  - Paths: Operations under specific path patterns
+
+Multiple values can be specified as comma-separated lists.`,
+		Example: `  # Slice specific operations by ID:
+  foascli slice -s spec.yaml -o subset.yaml --operation-ids "getUser,createUser"
+
+  # Slice operations by tags:
+  foascli slice -s spec.yaml -o subset.yaml --tags "Users,Authentication"
+
+  # Slice operations by path patterns:
+  foascli slice -s spec.yaml -o subset.yaml --paths "/api/v1/users"
+
+  # Combine multiple criteria:
+  foascli slice -s spec.yaml -o subset.yaml --tags "Users" --paths "/api/v1"`,
+		Args: cobra.NoArgs,
+		PreRunE: func(_ *cobra.Command, args []string) error {
+			return opts.PreRunE(args)
+		},
+		RunE: func(_ *cobra.Command, _ []string) error {
+			return opts.Run()
+		},
+	}
+
+	cmd.Flags().StringVarP(&opts.basePath, flag.Spec, flag.SpecShort, "-", usage.Spec)
+	cmd.Flags().StringVarP(&opts.outputPath, flag.Output, flag.OutputShort, "", usage.Output)
+	cmd.Flags().StringVarP(&opts.format, flag.Format, flag.FormatShort, openapi.ALL, usage.Format)
+	cmd.Flags().StringSliceVar(&opts.operationIDs, flag.OperationIDs, []string{}, usage.OperationIDs)
+	cmd.Flags().StringSliceVar(&opts.tags, flag.Tags, []string{}, usage.Tags)
+	cmd.Flags().StringSliceVar(&opts.paths, flag.Paths, []string{}, usage.Paths)
+
+	// Required flags
+	_ = cmd.MarkFlagRequired(flag.Output)
+	_ = cmd.MarkFlagRequired(flag.Spec)
+
+	return cmd
+}

tools/cli/internal/cli/slice/slice_test.go

@@ -0,0 +1,118 @@
+// Copyright 2024 MongoDB Inc
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//	http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package slice
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestOpts_PreRunE(t *testing.T) {
+	testCases := []struct {
+		name     string
+		opts     Opts
+		wantErr  require.ErrorAssertionFunc
+		errorMsg string
+	}{
+		{
+			name: "valid with operation IDs",
+			opts: Opts{
+				basePath:     "spec.yaml",
+				outputPath:   "output.yaml",
+				format:       "yaml",
+				operationIDs: []string{"op1", "op2"},
+			},
+			wantErr: require.NoError,
+		},
+		{
+			name: "valid with tags",
+			opts: Opts{
+				basePath:   "spec.yaml",
+				outputPath: "output.yaml",
+				format:     "yaml",
+				tags:       []string{"tag1", "tag2"},
+			},
+			wantErr: require.NoError,
+		},
+		{
+			name: "valid with paths",
+			opts: Opts{
+				basePath:   "spec.yaml",
+				outputPath: "output.yaml",
+				format:     "yaml",
+				paths:      []string{"/api/v1"},
+			},
+			wantErr: require.NoError,
+		},
+		{
+			name: "missing base path",
+			opts: Opts{
+				outputPath:   "output.yaml",
+				format:       "yaml",
+				operationIDs: []string{"op1"},
+			},
+			wantErr:  require.Error,
+			errorMsg: "no OAS detected",
+		},
+		{
+			name: "missing all criteria",
+			opts: Opts{
+				basePath:   "spec.yaml",
+				outputPath: "output.yaml",
+				format:     "yaml",
+			},
+			wantErr:  require.Error,
+			errorMsg: "at least one of --operation-ids, --tags, or --paths must be specified",
+		},
+	}
+
+	for _, tt := range testCases {
+		t.Run(tt.name, func(t *testing.T) {
+			err := tt.opts.PreRunE(nil)
+			tt.wantErr(t, err)
+			if tt.errorMsg != "" && err != nil {
+				assert.Contains(t, err.Error(), tt.errorMsg)
+			}
+		})
+	}
+}
+
+func TestInvalidFormat_PreRunE(t *testing.T) {
+	opts := &Opts{
+		outputPath: "slice.json",
+		basePath:   "base.json",
+		format:     "html",
+		paths:      []string{"/api/v1"},
+	}
+
+	err := opts.PreRunE(nil)
+	require.Error(t, err)
+	require.EqualError(t, err, "format must be either 'json', 'yaml' or 'all', got 'html'")
+}
+
+func TestInvalidPath_PreRunE(t *testing.T) {
+	opts := &Opts{
+		outputPath: "slice.html",
+		basePath:   "base.json",
+		format:     "all",
+		paths:      []string{"/api/v1"},
+	}
+
+	err := opts.PreRunE(nil)
+	require.Error(t, err)
+	require.EqualError(t, err, "output file must be either a JSON or YAML file, got slice.html")
+}

tools/cli/internal/cli/split/split.go

@@ -1,4 +1,4 @@
-// Copyright 2024 MongoDB Inc
+// Copyright 2025 MongoDB Inc
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

tools/cli/internal/cli/split/split_test.go

@@ -1,4 +1,4 @@
-// Copyright 2024 MongoDB Inc
+// Copyright 2025 MongoDB Inc
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

tools/cli/internal/cli/usage/usage.go

@@ -39,4 +39,7 @@ const (
 	To                  = "Date in the format YYYY-MM-DD that indicates the end of a date range"
 	StabilityLevel      = "Stability level related to the API Version. Valid values: [STABLE, UPCOMING, PUBLIC-PREVIEW, PRIVATE-PREVIEW]"
 	Version             = "Version of the API."
+	Tags                = "Comma-separated list of tags to extract."
+	OperationIDs        = "Comma-separated list of operation IDs to extract."
+	Paths               = "Comma-separated list of path patterns to extract."
 )

tools/cli/internal/openapi/filter/filter.go

@@ -102,6 +102,14 @@ func FiltersToGetVersions(oas *openapi3.T, metadata *Metadata) []Filter {
 	}
 }
 
+func FiltersToCleanupRefs(oas *openapi3.T) []Filter {
+	return []Filter{
+		&TagsFilter{oas: oas},
+		&SchemasFilter{oas: oas},
+		&ParametersFilter{oas: oas},
+	}
+}
+
 func ApplyFilters(doc *openapi3.T, metadata *Metadata, filters func(oas *openapi3.T, metadata *Metadata) []Filter) (*openapi3.T, error) {
 	if doc == nil {
 		return nil, errors.New("openapi document is nil")

tools/cli/internal/openapi/filter/parameters.go

@@ -0,0 +1,64 @@
+// Copyright 2025 MongoDB Inc
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//	http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package filter
+
+import (
+	"log"
+	"maps"
+	"strings"
+
+	"github.com/getkin/kin-openapi/openapi3"
+)
+
+type ParametersFilter struct {
+	oas *openapi3.T
+}
+
+func (*ParametersFilter) ValidateMetadata() error {
+	return nil
+}
+
+func (f *ParametersFilter) Apply() error {
+	if f.oas.Paths == nil {
+		return nil
+	}
+
+	if f.oas.Components == nil || f.oas.Components.Parameters == nil {
+		return nil
+	}
+
+	oasSpecAsBytes, err := f.oas.MarshalJSON()
+	if err != nil {
+		return err
+	}
+
+	spec := string(oasSpecAsBytes)
+	parametersToDelete := make([]string, 0)
+	for k := range f.oas.Components.Parameters {
+		ref := "#/components/parameters/" + k
+		if !strings.Contains(spec, ref) {
+			parametersToDelete = append(parametersToDelete, k)
+		}
+	}
+
+	for _, parameterToDelete := range parametersToDelete {
+		log.Printf("Deleting unused parameter: %q", parameterToDelete)
+		maps.DeleteFunc(f.oas.Components.Parameters, func(k string, _ *openapi3.ParameterRef) bool {
+			return k == parameterToDelete
+		})
+	}
+
+	return nil
+}