From 7b7f02738a30bba164fa3a624cd30851447a3fe3 Mon Sep 17 00:00:00 2001 From: Bianca Date: Fri, 9 Aug 2024 19:36:38 +0100 Subject: [PATCH 1/6] Add comments --- tools/cli/internal/openapi/filter/extension.go | 3 +++ tools/cli/internal/openapi/filter/hidden_envs.go | 2 ++ 2 files changed, 5 insertions(+) diff --git a/tools/cli/internal/openapi/filter/extension.go b/tools/cli/internal/openapi/filter/extension.go index c60e2660e2..15bb484fdb 100644 --- a/tools/cli/internal/openapi/filter/extension.go +++ b/tools/cli/internal/openapi/filter/extension.go @@ -21,6 +21,9 @@ import ( "github.com/mongodb/openapi/tools/cli/internal/apiversion" ) +// 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 diff --git a/tools/cli/internal/openapi/filter/hidden_envs.go b/tools/cli/internal/openapi/filter/hidden_envs.go index 54812566ac..b76a517372 100644 --- a/tools/cli/internal/openapi/filter/hidden_envs.go +++ b/tools/cli/internal/openapi/filter/hidden_envs.go @@ -25,6 +25,8 @@ const ( hiddenEnvsExtKey = "envs" ) +// 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 From ed4471dc1154ecc437cb38f5ee21579cbac6a15f Mon Sep 17 00:00:00 2001 From: Bianca Date: Mon, 12 Aug 2024 13:00:46 +0100 Subject: [PATCH 2/6] Add filters docs --- tools/cli/internal/openapi/filter/README.md | 19 +++++++++------ .../cli/internal/openapi/filter/extension.go | 2 +- .../internal/openapi/filter/hidden_envs.go | 2 +- tools/cli/internal/openapi/filter/info.go | 1 + .../cli/internal/openapi/filter/operations.go | 1 + tools/cli/internal/openapi/filter/tags.go | 1 + .../cli/internal/openapi/filter/versioning.go | 1 + tools/cli/scripts/doc_filters.sh | 23 +++++++++++++++++++ tools/cli/scripts/update_docs.sh | 11 +++++++++ 9 files changed, 52 insertions(+), 9 deletions(-) create mode 100755 tools/cli/scripts/doc_filters.sh create mode 100755 tools/cli/scripts/update_docs.sh diff --git a/tools/cli/internal/openapi/filter/README.md b/tools/cli/internal/openapi/filter/README.md index 3305241321..170d4aac7b 100644 --- a/tools/cli/internal/openapi/filter/README.md +++ b/tools/cli/internal/openapi/filter/README.md @@ -1,10 +1,15 @@ +# 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. \ No newline at end of file +### 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 and moves the x-sunset extension to the operation level.](../internal/openapi/filter/operations.go?plain=1#L20) +[VersioningFilter is a filter that modifies the OpenAPI spec by removing operations and responses that are not supported by the target version.](../internal/openapi/filter/versioning.go?plain=1#L24) diff --git a/tools/cli/internal/openapi/filter/extension.go b/tools/cli/internal/openapi/filter/extension.go index 15bb484fdb..f7c85a25b0 100644 --- a/tools/cli/internal/openapi/filter/extension.go +++ b/tools/cli/internal/openapi/filter/extension.go @@ -21,7 +21,7 @@ import ( "github.com/mongodb/openapi/tools/cli/internal/apiversion" ) -// ExtensionFilter is a filter that updates the x-sunset and x-xgen-version extensions to a date string +// 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 { diff --git a/tools/cli/internal/openapi/filter/hidden_envs.go b/tools/cli/internal/openapi/filter/hidden_envs.go index b76a517372..da74637bcf 100644 --- a/tools/cli/internal/openapi/filter/hidden_envs.go +++ b/tools/cli/internal/openapi/filter/hidden_envs.go @@ -25,7 +25,7 @@ const ( hiddenEnvsExtKey = "envs" ) -// HiddenEnvsFilter is a filter that removes paths, operations, +// 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 diff --git a/tools/cli/internal/openapi/filter/info.go b/tools/cli/internal/openapi/filter/info.go index 6e5721446c..03b4fe7afd 100644 --- a/tools/cli/internal/openapi/filter/info.go +++ b/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 diff --git a/tools/cli/internal/openapi/filter/operations.go b/tools/cli/internal/openapi/filter/operations.go index 763c3bd27c..d30745e1ab 100644 --- a/tools/cli/internal/openapi/filter/operations.go +++ b/tools/cli/internal/openapi/filter/operations.go @@ -17,6 +17,7 @@ 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 } diff --git a/tools/cli/internal/openapi/filter/tags.go b/tools/cli/internal/openapi/filter/tags.go index e792156ebd..eda23744c7 100644 --- a/tools/cli/internal/openapi/filter/tags.go +++ b/tools/cli/internal/openapi/filter/tags.go @@ -19,6 +19,7 @@ import ( "github.com/getkin/kin-openapi/openapi3" ) +// TagsFilter removes tags that are not used in the operations. type TagsFilter struct { oas *openapi3.T } diff --git a/tools/cli/internal/openapi/filter/versioning.go b/tools/cli/internal/openapi/filter/versioning.go index 96e531a96d..e2ba90e6f9 100644 --- a/tools/cli/internal/openapi/filter/versioning.go +++ b/tools/cli/internal/openapi/filter/versioning.go @@ -21,6 +21,7 @@ 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 diff --git a/tools/cli/scripts/doc_filters.sh b/tools/cli/scripts/doc_filters.sh new file mode 100755 index 0000000000..782a90f90d --- /dev/null +++ b/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 | grep "is a filter" | sort -u -k2 | sed -n "s/\([^0-9]*\):\([0-9]*\):\/\/ Filter: \(.*\)/[\3](\.\.\/\1?plain=1#L\2) /p" | sort + diff --git a/tools/cli/scripts/update_docs.sh b/tools/cli/scripts/update_docs.sh new file mode 100755 index 0000000000..46b0b43540 --- /dev/null +++ b/tools/cli/scripts/update_docs.sh @@ -0,0 +1,11 @@ +#!/bin/bash + +set -euxo pipefail + +# Update the filters documentation + +./scripts/doc_filters.sh > internal/openapi/filter/README.md + +go fmt ./... + +git add "internal/openapi/filter/README.md" \ No newline at end of file From d2baca2add39a1408be5dc026173e18a6eb223b5 Mon Sep 17 00:00:00 2001 From: Bianca Date: Mon, 12 Aug 2024 13:13:04 +0100 Subject: [PATCH 3/6] Update --- tools/cli/internal/openapi/filter/operations.go | 3 ++- tools/cli/internal/openapi/filter/versioning.go | 3 ++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/tools/cli/internal/openapi/filter/operations.go b/tools/cli/internal/openapi/filter/operations.go index d30745e1ab..e16addcc0a 100644 --- a/tools/cli/internal/openapi/filter/operations.go +++ b/tools/cli/internal/openapi/filter/operations.go @@ -17,7 +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. +// 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 } diff --git a/tools/cli/internal/openapi/filter/versioning.go b/tools/cli/internal/openapi/filter/versioning.go index e2ba90e6f9..07845d2ba5 100644 --- a/tools/cli/internal/openapi/filter/versioning.go +++ b/tools/cli/internal/openapi/filter/versioning.go @@ -21,7 +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. +// 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 From 31802b5758a3e4f1ed0855d4417af0895faa0a73 Mon Sep 17 00:00:00 2001 From: Bianca Date: Mon, 12 Aug 2024 13:13:59 +0100 Subject: [PATCH 4/6] Update --- tools/cli/Makefile | 4 ++++ tools/cli/internal/openapi/filter/README.md | 4 ++-- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/tools/cli/Makefile b/tools/cli/Makefile index 8eb7bb956d..59d70b2233 100644 --- a/tools/cli/Makefile +++ b/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 diff --git a/tools/cli/internal/openapi/filter/README.md b/tools/cli/internal/openapi/filter/README.md index 170d4aac7b..de910c1fa1 100644 --- a/tools/cli/internal/openapi/filter/README.md +++ b/tools/cli/internal/openapi/filter/README.md @@ -11,5 +11,5 @@ The Atlas Admin API OpenAPI specifications are used not only to document REST en [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 and moves the x-sunset extension to the operation level.](../internal/openapi/filter/operations.go?plain=1#L20) -[VersioningFilter is a filter that modifies the OpenAPI spec by removing operations and responses that are not supported by the target version.](../internal/openapi/filter/versioning.go?plain=1#L24) +[OperationsFilter is a filter that removes the x-xgen-owner-team extension from operations](../internal/openapi/filter/operations.go?plain=1#L20) +[VersioningFilter is a filter that modifies the OpenAPI spec by removing operations and responses](../internal/openapi/filter/versioning.go?plain=1#L24) From 9e8ee7706acf021f37e62e93423f60586a2a92f9 Mon Sep 17 00:00:00 2001 From: Bianca Date: Mon, 12 Aug 2024 13:14:55 +0100 Subject: [PATCH 5/6] Update --- tools/cli/internal/openapi/filter/tags.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tools/cli/internal/openapi/filter/tags.go b/tools/cli/internal/openapi/filter/tags.go index eda23744c7..c7314ad3c1 100644 --- a/tools/cli/internal/openapi/filter/tags.go +++ b/tools/cli/internal/openapi/filter/tags.go @@ -19,7 +19,7 @@ import ( "github.com/getkin/kin-openapi/openapi3" ) -// TagsFilter removes tags that are not used in the operations. +// Filter: TagsFilter removes tags that are not used in the operations. type TagsFilter struct { oas *openapi3.T } From b7a2b093c78e9f0d79f4bcd3149ce66b3912364c Mon Sep 17 00:00:00 2001 From: Bianca Date: Mon, 12 Aug 2024 13:17:20 +0100 Subject: [PATCH 6/6] Update --- tools/cli/internal/openapi/filter/README.md | 1 + tools/cli/scripts/doc_filters.sh | 2 +- tools/cli/scripts/update_docs.sh | 5 +++-- 3 files changed, 5 insertions(+), 3 deletions(-) diff --git a/tools/cli/internal/openapi/filter/README.md b/tools/cli/internal/openapi/filter/README.md index de910c1fa1..3649d28371 100644 --- a/tools/cli/internal/openapi/filter/README.md +++ b/tools/cli/internal/openapi/filter/README.md @@ -12,4 +12,5 @@ The Atlas Admin API OpenAPI specifications are used not only to document REST en [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) diff --git a/tools/cli/scripts/doc_filters.sh b/tools/cli/scripts/doc_filters.sh index 782a90f90d..8e72146acd 100755 --- a/tools/cli/scripts/doc_filters.sh +++ b/tools/cli/scripts/doc_filters.sh @@ -19,5 +19,5 @@ echo " - Filtering per version, so that only the endpoints that are available in echo "## What filters are available?" echo "### List of filters" -grep -n '// Filter:' internal/openapi/filter/*.go | grep "is a filter" | sort -u -k2 | sed -n "s/\([^0-9]*\):\([0-9]*\):\/\/ Filter: \(.*\)/[\3](\.\.\/\1?plain=1#L\2) /p" | sort +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 diff --git a/tools/cli/scripts/update_docs.sh b/tools/cli/scripts/update_docs.sh index 46b0b43540..432f296a93 100755 --- a/tools/cli/scripts/update_docs.sh +++ b/tools/cli/scripts/update_docs.sh @@ -3,9 +3,10 @@ set -euxo pipefail # Update the filters documentation - ./scripts/doc_filters.sh > internal/openapi/filter/README.md go fmt ./... -git add "internal/openapi/filter/README.md" \ No newline at end of file +if [ -n "$(git status --porcelain internal/openapi/filter/README.md)" ]; then + git add "internal/openapi/filter/README.md" +fi \ No newline at end of file