chore: add comments

tools/cli/Makefile

@@ -74,6 +74,10 @@ e2e-test: build ## Run E2E tests
 	@echo "==> Running E2E tests..."
 	$(TEST_CMD) -v -p 1 -parallel $(E2E_PARALLEL) -timeout $(E2E_TIMEOUT)  ./test/e2e... $(E2E_EXTRA_ARGS)
 
+.PHONY: gen-docs
+gen-docs: ## Generate docs
+	@echo "==> Updating docs"
+	./scripts/update_docs.sh
 
 .PHONY: unit-test
 unit-test: ## Run unit-tests

tools/cli/internal/openapi/filter/README.md

@@ -1,10 +1,16 @@
+# List of filters applied to the OpenAPI specification
+These examples are automatically generated from filters docs.
 # OpenAPI Filters
-
 ## Why filtering OpenAPI?
-
-The Atlas Admin API OpenAPI specifications are used not only to document REST endpoints, but also to capture extra functionality such as Versioning information, team ownership, and more. This extra information is used to then correctly generate the OpenAPI respective to each version of the API. 
-
+The Atlas Admin API OpenAPI specifications are used not only to document REST endpoints, but also to capture extra functionality such as Versioning information, team ownership, and more. This extra information is used to then correctly generate the OpenAPI respective to each version of the API.
+## What is the general filter purpose?
+ - Filtering per environment, so that only the endpoints that are available in that environment are shown.
+ - Filtering per version, so that only the endpoints that are available in that version are shown.
 ## What filters are available?
-
-- Filtering per environment, so that only the endpoints that are available in that environment are shown.
-- Filtering per version, so that only the endpoints that are available in that version are shown.
+### List of filters
+[ExtensionFilter is a filter that updates the x-sunset and x-xgen-version extensions to a date string](../internal/openapi/filter/extension.go?plain=1#L24)  
+[HiddenEnvsFilter is a filter that removes paths, operations,](../internal/openapi/filter/hidden_envs.go?plain=1#L28)  
+[InfoFilter is a filter that modifies the Info object in the OpenAPI spec.](../internal/openapi/filter/info.go?plain=1#L23)  
+[OperationsFilter is a filter that removes the x-xgen-owner-team extension from operations](../internal/openapi/filter/operations.go?plain=1#L20)  
+[TagsFilter removes tags that are not used in the operations.](../internal/openapi/filter/tags.go?plain=1#L22)  
+[VersioningFilter is a filter that modifies the OpenAPI spec by removing operations and responses](../internal/openapi/filter/versioning.go?plain=1#L24)  

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

@@ -21,6 +21,9 @@ import (
 	"github.com/mongodb/openapi/tools/cli/internal/apiversion"
 )
 
+// Filter: ExtensionFilter is a filter that updates the x-sunset and x-xgen-version extensions to a date string
+// and deletes the x-sunset extension if the latest matched version is deprecated by hidden versions
+// for the target environment
 type ExtensionFilter struct {
 	oas      *openapi3.T
 	metadata *Metadata

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

@@ -25,6 +25,8 @@ const (
 	hiddenEnvsExtKey    = "envs"
 )
 
+// Filter: HiddenEnvsFilter is a filter that removes paths, operations,
+// request/response bodies and content types that are hidden for the target environment
 type HiddenEnvsFilter struct {
 	oas      *openapi3.T
 	metadata *Metadata

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

@@ -20,6 +20,7 @@ import (
 	"github.com/mongodb/openapi/tools/cli/internal/apiversion"
 )
 
+// Filter: InfoFilter is a filter that modifies the Info object in the OpenAPI spec.
 type InfoFilter struct {
 	oas      *openapi3.T
 	metadata *Metadata

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

@@ -17,6 +17,8 @@ import (
 	"github.com/getkin/kin-openapi/openapi3"
 )
 
+// Filter: OperationsFilter is a filter that removes the x-xgen-owner-team extension from operations
+// and moves the x-sunset extension to the operation level.
 type OperationsFilter struct {
 	oas *openapi3.T
 }

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

@@ -19,6 +19,7 @@ import (
 	"github.com/getkin/kin-openapi/openapi3"
 )
 
+// Filter: TagsFilter removes tags that are not used in the operations.
 type TagsFilter struct {
 	oas *openapi3.T
 }

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

@@ -21,6 +21,8 @@ import (
 	"github.com/mongodb/openapi/tools/cli/internal/apiversion"
 )
 
+// Filter: VersioningFilter is a filter that modifies the OpenAPI spec by removing operations and responses
+// that are not supported by the target version.
 type VersioningFilter struct {
 	oas      *openapi3.T
 	metadata *Metadata

tools/cli/scripts/doc_filters.sh

@@ -0,0 +1,23 @@
+#!/bin/sh
+
+echo "# List of filters applied to the OpenAPI specification"
+echo "These examples are automatically generated from filters docs."
+
+# Expected format:
+# // Filter: InfoFilter is a filter that modifies the Info object in the OpenAPI spec.
+
+echo "# OpenAPI Filters"
+
+echo "## Why filtering OpenAPI?"
+
+echo "The Atlas Admin API OpenAPI specifications are used not only to document REST endpoints, but also to capture extra functionality such as Versioning information, team ownership, and more. This extra information is used to then correctly generate the OpenAPI respective to each version of the API."
+
+echo "## What is the general filter purpose?"
+echo " - Filtering per environment, so that only the endpoints that are available in that environment are shown."
+echo " - Filtering per version, so that only the endpoints that are available in that version are shown."
+
+echo "## What filters are available?"
+
+echo "### List of filters"
+grep -n '// Filter:' internal/openapi/filter/*.go | sort -u -k2 | sed -n "s/\([^0-9]*\):\([0-9]*\):\/\/ Filter: \(.*\)/[\3](\.\.\/\1?plain=1#L\2)  /p" | sort
+

tools/cli/scripts/update_docs.sh

@@ -0,0 +1,12 @@
+#!/bin/bash
+
+set -euxo pipefail
+
+# Update the filters documentation
+./scripts/doc_filters.sh > internal/openapi/filter/README.md
+
+go fmt ./...
+
+if [ -n "$(git status --porcelain internal/openapi/filter/README.md)" ]; then
+    git add "internal/openapi/filter/README.md"
+fi