feat: add slice command to filter OpenAPI specs #1056

andmatei · 2025-12-18T09:56:18Z

Proposed changes

This PR adds a new slice command to the foascli that enables users to slice/filter OpenAPI specifications by operation IDs, tags, or path patterns. This feature allows developers to create smaller, focused OpenAPI specs containing only the endpoints they need

Example usage:

# Extract only Alerts endpoints by tag
foascli slice -s openapi/.raw/v2.yaml -o alerts-only.yaml --tags Alerts

# Extract specific operations
foascli slice -s spec.yaml -o output.yaml --operation-ids "getUser,createUser"

# Extract by path pattern
foascli slice -s spec.yaml -o output.yaml --paths "/api/v1/users"

Jira ticket: CLOUDP-365849

Checklist

I have signed the MongoDB CLA
I have added tests that prove my fix is effective or that my feature works

Changes to Spectral

I have read the README file for Spectral Updates

Further comments

…ation IDs, and paths - Add new 'extract' CLI command to slice OpenAPI specifications - Support filtering by operation IDs, tags, and path patterns - Implement SliceFilter with comprehensive test coverage - Use Cobra's StringSliceVar for cleaner flag handling - Include all referenced schemas and components in output - Add validation for input parameters and output formats - Support both YAML and JSON output formats

- Update command name from 'extract' to 'slice' for consistency - Update all examples and documentation to use 'slice' - All tests still pass

- Fix perfsprint linter error - Use errors.New instead of fmt.Errorf when no formatting is needed - Add errors import

- Replace fmt.Errorf with errors.New for non-formatted errors (perfsprint) - Fix receiver naming consistency in SliceFilter.matches method (revive) - Change receiver name from 'e' to 'f' to match other methods

- Add ParametersFilter to remove unused parameters from OpenAPI specs - Add comprehensive tests for ParametersFilter (7 test scenarios) - Move slice functionality from filter package to dedicated slice package - Update FiltersToCleanupRefs to include TagsFilter, ParametersFilter, and SchemasFilter - Fix linting issues (import shadowing and missing period in comment) - Slice command now cleans up unused tags, parameters, and schemas automatically

yelizhenden-mdb · 2025-12-19T14:09:38Z

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

+				Version: "1.0",
+			},
+			Paths: openapi3.NewPaths(openapi3.WithPath("/test/{id}", &openapi3.PathItem{
+				Parameters: openapi3.Parameters{


Could you help me to understand the equivalent of this Parameters field under PathItem in the OpenAPI spec?

Or, would it make more sense under Get operation?

Of course, so in this example the path is /test/{id} so the path parameter would refer to id and the type it references. All parameters types are under components.parameter in the OpenAPI spec with refer to path and query parameters. Since this is a parameter for the endpoint path, it is not associated with an operation (i.e. GET, UPDATE etc.) Let me know if this clarifies everything!

In our MMS OpenAPI spec we currently don’t use parameters in a way that applies to all operations under an endpoint. To stay consistent, it may be better to follow the same structure we already use

Based on the example, I would normally expect something like this to exist:

/test/{id}: parameters: - name: id in: path required: true schema: type: string get: …

Oh yes I see that now, thank you for clarifying, will update the test cases for this!

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

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

andreaangiolillo · 2025-12-22T09:11:40Z

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

+	// Check if the path matches (with normalization)
+	normalizedPath := normalizePath(path)
+	for _, pattern := range criteria.Paths {
+		if normalizedPath == normalizePath(pattern) {


[q] does the path mtaches nested resources? ie, if I provide --filterPath atlas/api/v2, will the slice command return an openapi spec with all the resources?

For this PR, endpoint paths that match exactly will be selected in the output spec. I can add in a follow-up PR support for regex path matching

no, there is no need to add the logic if you won't use it. Just makes sure to include this clarification in the command or flag description

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

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

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

andreaangiolillo · 2025-12-22T09:33:45Z

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

+	if f.oas.Components == nil || f.oas.Components.Schemas == nil {
+		return nil
+	}


in which scenario we have components or components.schemas nil? Note that when we load the spec with the openapi repo, we are also performing a validation that all the references in the endpoints are correctly in the component section

Was thinking for the scenarios where all the response / request bodies are inline for each API endpoint, in that case the Schemas could contain nothing

andmatei added 4 commits December 18, 2025 11:46

refactor: rename command from 'extract' to 'slice'

208c7e4

- Update command name from 'extract' to 'slice' for consistency - Update all examples and documentation to use 'slice' - All tests still pass

fix: replace fmt.Errorf with errors.New for non-formatted error

81a8f6a

- Fix perfsprint linter error - Use errors.New instead of fmt.Errorf when no formatting is needed - Add errors import

fix: resolve golangci-lint issues

dc4fab3

- Replace fmt.Errorf with errors.New for non-formatted errors (perfsprint) - Fix receiver naming consistency in SliceFilter.matches method (revive) - Change receiver name from 'e' to 'f' to match other methods

andmatei changed the title ~~feat: add slice command to filter OpenAPI specs~~ feat(foascli): add slice command to filter OpenAPI specs Dec 19, 2025

andmatei changed the title ~~feat(foascli): add slice command to filter OpenAPI specs~~ feat: add slice command to filter OpenAPI specs Dec 19, 2025

andmatei marked this pull request as ready for review December 19, 2025 09:47

andmatei requested a review from a team as a code owner December 19, 2025 09:47

andmatei requested review from andreaangiolillo, drinkbird, lovisaberggren, matt-condon, wtrocki and yelizhenden-mdb December 19, 2025 09:47

fix: add flag and usage for the slice parameters

43e2294

yelizhenden-mdb reviewed Dec 19, 2025

View reviewed changes

tools/cli/internal/openapi/filter/parameters_test.go Show resolved Hide resolved

andreaangiolillo reviewed Dec 22, 2025

View reviewed changes

fix: fix copyright & require at least one criteria to be set for slicing

564ee61

andmatei requested review from andreaangiolillo and yelizhenden-mdb December 22, 2025 11:14

andreaangiolillo approved these changes Dec 22, 2025

View reviewed changes

andmatei merged commit 76e8db4 into main Dec 22, 2025
11 checks passed

andmatei deleted the feature/add-slice-command branch December 22, 2025 17:49

andmatei mentioned this pull request Dec 23, 2025

fix: fix schema filter to remove unused schemas with circular dependencies #1062

Merged

3 tasks

feat: add slice command to filter OpenAPI specs #1056

feat: add slice command to filter OpenAPI specs #1056

Uh oh!

Conversation

andmatei commented Dec 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Proposed changes

Checklist

Changes to Spectral

Further comments

Uh oh!

yelizhenden-mdb Dec 19, 2025

Choose a reason for hiding this comment

Uh oh!

yelizhenden-mdb Dec 19, 2025

Choose a reason for hiding this comment

Uh oh!

andmatei Dec 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

yelizhenden-mdb Dec 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

andmatei Dec 22, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

andreaangiolillo Dec 22, 2025

Choose a reason for hiding this comment

Uh oh!

andmatei Dec 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

andreaangiolillo Dec 22, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

andreaangiolillo Dec 22, 2025

Choose a reason for hiding this comment

Uh oh!

andmatei Dec 22, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

andmatei commented Dec 18, 2025 •

edited

Loading

andmatei Dec 22, 2025 •

edited

Loading

yelizhenden-mdb Dec 22, 2025 •

edited

Loading

andmatei Dec 22, 2025 •

edited

Loading