Merge pull request #4 from zguydev/dev

feat: collect refs on components filter

Author: zguydev

README.md

@@ -37,9 +37,9 @@ The filter configuration file (e.g., `.openapi-filter.yaml`) specifies what part
 # Tool-specific configurations (optional)
 x-openapi-filter:
   logger:
-    level: info # e.g., debug, info, warn, error
+    level: info # Log level (e.g., "debug", "info", "warn", "error")
   loader:
-    external_refs_allowed: false # Controls resolution of external $refs
+    external_refs_allowed: false # Whether to allow external references
 
 # Keep or discard server information (default: false)
 servers: true
@@ -53,13 +53,9 @@ externalDocs: true
 # Specify paths and methods to keep.
 # If a path is listed, only the specified methods are kept.
 paths:
-  /pets:
-    - post
-    - put
-  /pet/{petId}/uploadImage:
-    - post
-  /user/login:
-    - get
+  /pets: [ post, put ]
+  /pet/{petId}/uploadImage: [ post ]
+  /user/login: [ get ]
   # Paths not listed here will be removed.
 
 # Specify components to keep.
@@ -70,8 +66,8 @@ components:
     - User
     - Error
   securitySchemes:
-    - bearerAuth
-  # Components not listed (and not referenced) will be removed.
+    - petstore_auth
+  # Components not listed (that are not referenced from kept paths) will be removed.
 ```
 
 ## Examples

example.openapi-filter.toml

@@ -11,7 +11,7 @@ external_refs_allowed = false
 
 [paths]
 "/api/example" = [ "get", "post" ]
-"/api/some-another" = [ "put" ]
+"/api/some-another-example" = [ "put" ]
 
 [components]
 securitySchemes = [ "ApiKeyAuth" ]

example.openapi-filter.yaml

@@ -10,11 +10,8 @@ tags: true
 externalDocs: false
 
 paths:
-  /api/example:
-    - get
-    - post
-  /api/some-another:
-    - put
+  /api/example: [ get, post ]
+  /api/some-another-example: [ put ]
 
 components:
   securitySchemes:

examples/OpenAI/.openapi-filter.yaml

@@ -3,14 +3,12 @@ x-openapi-filter:
     level: debug
 
 servers: true
+security: true
+tags: true
 
 paths:
-  /chat/completions:
-    - post
+  /chat/completions: [ post ]
 
 components:
   securitySchemes:
     - ApiKeyAuth
-
-security: true
-tags: true

examples/petstore/.openapi-filter.yaml

@@ -8,13 +8,9 @@ tags: true
 externalDocs: true
 
 paths:
-  /pet:
-    - put
-    - post
-  /pet/{petId}/uploadImage:
-    - post
-  /user/login:
-    - get
+  /pet: [ post, put ]
+  /pet/{petId}/uploadImage: [ post ]
+  /user/login: [ get ]
 
 components:
   securitySchemes:

internal/config/config.go

@@ -1,40 +1,52 @@
+// Package config provides configuration structures for the OpenAPI filter tool.
+// It defines the configuration format for filtering OpenAPI specs and
+// tool-specific settings.
 package config
 
+// Config represents the root configuration structure for the OpenAPI filter tool.
+// It combines tool-specific settings with filter configuration.
 type Config struct {
 	Tool         ToolConfig `koanf:"x-openapi-filter"`
 	FilterConfig `koanf:",squash"`
 }
 
+// FilterConfig defines the configuration for filtering an OpenAPI spec.
+// It specifies which parts of the spec should be included in the output.
 type FilterConfig struct {
-	Servers      bool                    `koanf:"servers"`
-	Paths        map[string][]string     `koanf:"paths"`
-	Components   *FilterComponentsConfig `koanf:"components"`
-	Security     bool                    `koanf:"security"`
-	Tags         bool                    `koanf:"tags"`
-	ExternalDocs bool                    `koanf:"externalDocs"`
+	Servers      bool                    `koanf:"servers"`      // Include servers section
+	Paths        map[string][]string     `koanf:"paths"`        // Map of paths to allowed HTTP methods
+	Components   *FilterComponentsConfig `koanf:"components"`   // Component filtering configuration
+	Security     bool                    `koanf:"security"`     // Include security requirements
+	Tags         bool                    `koanf:"tags"`         // Include tags
+	ExternalDocs bool                    `koanf:"externalDocs"` // Include external documentation
 }
 
+// FilterComponentsConfig specifies which components should be included in the
+// filtered OpenAPI spec. Each field is a list of component names to include.
 type FilterComponentsConfig struct {
-	Schemas         []string `koanf:"schemas"`
-	Parameters      []string `koanf:"parameters"`
-	SecuritySchemes []string `koanf:"securitySchemes"`
-	RequestBodies   []string `koanf:"requestBodies"`
-	Responses       []string `koanf:"responses"`
-	Headers         []string `koanf:"headers"`
-	Examples        []string `koanf:"examples"`
-	Links           []string `koanf:"links"`
-	Callbacks       []string `koanf:"callbacks"`
+	Schemas         []string `koanf:"schemas"`         // List of schema names to include
+	Parameters      []string `koanf:"parameters"`      // List of parameter names to include
+	SecuritySchemes []string `koanf:"securitySchemes"` // List of security scheme names to include
+	RequestBodies   []string `koanf:"requestBodies"`   // List of request body names to include
+	Responses       []string `koanf:"responses"`       // List of response names to include
+	Headers         []string `koanf:"headers"`         // List of header names to include
+	Examples        []string `koanf:"examples"`        // List of example names to include
+	Links           []string `koanf:"links"`           // List of link names to include
+	Callbacks       []string `koanf:"callbacks"`       // List of callback names to include
 }
 
+// ToolConfig contains tool-specific configuration settings.
 type ToolConfig struct {
-	Logger *LoggerConfig `koanf:"logger"`
-	Loader *LoaderConfig `koanf:"loader"`
+	Logger *LoggerConfig `koanf:"logger"` // Logger configuration
+	Loader *LoaderConfig `koanf:"loader"` // OpenAPI loader configuration
 }
 
+// LoggerConfig defines the logging configuration for the tool.
 type LoggerConfig struct {
-	Level string `koanf:"level"`
+	Level string `koanf:"level"` // Log level (e.g., "debug", "info", "warn", "error")
 }
 
+// LoaderConfig defines configuration for the OpenAPI spec loader.
 type LoaderConfig struct {
-	IsExternalRefsAllowed bool `koanf:"external_refs_allowed"`
+	IsExternalRefsAllowed bool `koanf:"external_refs_allowed"` // Whether to allow external references
 }

internal/filter/filter.go

@@ -1,3 +1,6 @@
+// Package filter provides functionality to filter OpenAPI specs based
+// on config. It allows filtering of paths, methods, components,
+// and other OpenAPI elements while maintaining the integrity of the spec.
 package filter
 
 import (
@@ -10,14 +13,18 @@ import (
 	"github.com/zguydev/openapi-filter/internal/config"
 )
 
+// OpenAPISpecFilter is the main type that handles filtering of OpenAPI specs.
 type OpenAPISpecFilter struct {
-	cfg    *config.FilterConfig
-	logger *zap.Logger
-	loader *openapi3.Loader
+	cfg       *config.FilterConfig
+	logger    *zap.Logger
+	loader    *openapi3.Loader
+	collector *RefsCollector
 
-	filtered, doc *openapi3.T
+	doc, filtered *openapi3.T
 }
 
+// NewOpenAPISpecFilter creates a new OpenAPISpecFilter instance with the
+// provided configuration and logger. It initializes the OpenAPI loader.
 func NewOpenAPISpecFilter(
 	cfg *config.Config,
 	logger *zap.Logger,
@@ -28,12 +35,23 @@ func NewOpenAPISpecFilter(
 	}
 
 	return &OpenAPISpecFilter{
-		cfg:    &cfg.FilterConfig,
-		logger: logger,
-		loader: loader,
+		cfg:       &cfg.FilterConfig,
+		logger:    logger,
+		loader:    loader,
+		collector: NewRefsCollector(),
 	}
 }
 
+// Filter processes an OpenAPI spec file according to the configured
+// filters and writes the filtered result to the specified output path.
+// It handles loading, filtering, and writing of the spec while
+// maintaining all necessary references and components.
+//
+// Parameters:
+//   - inputSpecPath: Path to the input OpenAPI spec file
+//   - outSpecPath: Path where the filtered spec will be written
+//
+// Returns an error if any step of the filtering process fails.
 func (oaf *OpenAPISpecFilter) Filter(inputSpecPath, outSpecPath string) error {
 	var err error
 	oaf.doc, err = loadSpecFromFile(oaf.loader, inputSpecPath)
@@ -49,11 +67,10 @@ func (oaf *OpenAPISpecFilter) Filter(inputSpecPath, outSpecPath string) error {
 		Paths:      &openapi3.Paths{},
 	}
 
-	collector := NewRefsCollector()
-
-	oaf.filterPaths(collector)
+	oaf.filterPaths()
 	oaf.filterComponents()
 	oaf.filterOther()
+	oaf.filterRefs()
 	if isEmptyComponents(oaf.filtered.Components) {
 		oaf.filtered.Components = nil
 	}
@@ -67,7 +84,10 @@ func (oaf *OpenAPISpecFilter) Filter(inputSpecPath, outSpecPath string) error {
 	return nil
 }
 
-func (oaf *OpenAPISpecFilter) filterPaths(collector *RefsCollector) {
+// filterPaths processes the paths specified in the configuration and filters them
+// according to the allowed methods. It also collects all references used in the
+// filtered paths.
+func (oaf *OpenAPISpecFilter) filterPaths() {
 	for path, methods := range oaf.cfg.Paths {
 		pathItem := oaf.doc.Paths.Find(path)
 		if pathItem == nil {
@@ -80,37 +100,41 @@ func (oaf *OpenAPISpecFilter) filterPaths(collector *RefsCollector) {
 			op := oaf.getOperation(pathItem, method, path)
 			if op == nil {
 				oaf.logger.Warn("method not exists for specified path",
-					zap.String("path", path),
-					zap.String("method", method))
+					zap.String("method", method),
+					zap.String("path", path))
 				continue
 			}
 			if !oaf.setOperation(newPathItem, method, path, op) {
 				continue
 			}
-			collector.CollectOperation(op)
+			oaf.collector.CollectOperation(op)
 		}
 
 		oaf.filtered.Paths.Set(path, newPathItem)
 	}
-
-	oaf.filterRefs(collector.Refs())
 }
 
+// getOperation safely retrieves an operation from a PathItem for the specified
+// method. It handles unknown HTTP methods gracefully and returns nil if the
+// method is invalid.
 func (oaf *OpenAPISpecFilter) getOperation(
 	p *openapi3.PathItem,
 	method, path string,
 ) (op *openapi3.Operation) {
 	defer func() {
 		if r := recover(); r != nil {
 			oaf.logger.Warn("unknown HTTP method in filter config",
-				zap.String("path", path),
-				zap.String("method", method))
+				zap.String("method", method),
+				zap.String("path", path))
 			op = nil
 		}
 	}()
 	return p.GetOperation(strings.ToUpper(method))
 }
 
+// setOperation safely sets an operation in a PathItem for the specified method.
+// It handles unknown HTTP methods gracefully and returns false if the method
+// is invalid.
 func (oaf *OpenAPISpecFilter) setOperation(
 	p *openapi3.PathItem,
 	method, path string,
@@ -119,21 +143,25 @@ func (oaf *OpenAPISpecFilter) setOperation(
 	defer func() {
 		if r := recover(); r != nil {
 			oaf.logger.Warn("unknown HTTP method in spec",
-				zap.String("path", path),
-				zap.String("method", method))
+				zap.String("method", method),
+				zap.String("path", path))
 			ok = false
 		}
 	}()
 	p.SetOperation(strings.ToUpper(method), operation)
 	return true
 }
 
-func (oaf *OpenAPISpecFilter) filterRefs(refs map[string]struct{}) {
-	for ref := range refs {
+// filterRefs processes all collected references and ensures they are properly
+// included in the filtered spec.
+func (oaf *OpenAPISpecFilter) filterRefs() {
+	for ref := range oaf.collector.refs {
 		oaf.filterRef(ref)
 	}
 }
 
+// filterRef processes a single reference and copies the referenced component
+// to the filtered spec.
 func (oaf *OpenAPISpecFilter) filterRef(ref string) {
 	if oaf.doc.Components == nil {
 		return
@@ -148,39 +176,49 @@ func (oaf *OpenAPISpecFilter) filterRef(ref string) {
 	compType, ok := ComponentDefToType(def)
 	if !ok {
 		oaf.logger.Warn("unknown component definition",
-			zap.String("def", def), zap.String("ref", ref))
+			zap.String("def", def),
+			zap.String("name", name),
+			zap.String("ref", ref))
 		return
 	}
-	if !processCopyComponent(
-		oaf.doc.Components,
+	if !processCopyComponent(oaf.doc.Components,
 		oaf.filtered.Components,
-		compType, name) {
+		compType,
+		name,
+	) {
 		oaf.logger.Warn("component not found",
-			zap.String("name", name),
 			zap.String("def", def),
+			zap.String("name", name),
 			zap.String("ref", ref))
 	}
 }
 
+// filterComponents processes all components specified in the configuration and
+// copies them to the filtered spec.
 func (oaf *OpenAPISpecFilter) filterComponents() {
 	if oaf.cfg.Components == nil || oaf.doc.Components == nil {
 		return
 	}
 
 	for _, compTyp := range ComponentTypes() {
 		for _, name := range ComponentTypeToCfgNames(oaf.cfg.Components, compTyp) {
-			if !processCopyComponent(
-				oaf.doc.Components,
+			if !processCopyComponent(oaf.doc.Components,
 				oaf.filtered.Components,
-				compTyp, name) {
+				compTyp,
+				name,
+			) {
 				oaf.logger.Warn("component not found",
-					zap.String("name", name),
-					zap.String("def", ComponentTypeToDef(compTyp)))
+					zap.String("def", ComponentTypeToDef(compTyp)),
+					zap.String("name", name))
+				continue
 			}
+			CollectComponent(oaf.collector, oaf.doc.Components, compTyp, name)
 		}
 	}
 }
 
+// filterOther processes additional OpenAPI elements specified in the configuration,
+// including servers, security requirements, tags, and external documentation.
 func (oaf *OpenAPISpecFilter) filterOther() {
 	if oaf.cfg.Servers {
 		oaf.filtered.Servers = oaf.doc.Servers