diff --git a/README.md b/README.md index b5fbf45fd6..2983b68d86 100644 --- a/README.md +++ b/README.md @@ -15,8 +15,8 @@ The [tools/cli](tools/cli) directory hosts a Go-based CLI tool used to merge mul For more details, please refer to the [CLI’s README.md](tools/cli/README.md). ### Spectral -The [tools/spectral](tools/spectral) directory contains MongoDB-specific [Spectral](https://github.com/stoplightio/spectral) rule definitions. -These rules are used to validate that the generated OpenAPI specifications comply with MongoDB’s guidelines. +The [tools/spectral](tools/spectral) directory contains [Spectral](https://github.com/stoplightio/spectral) rule definitions. +These rules are used to validate that the generated OpenAPI specifications comply with MongoDB's [Improvement Proposal for APIs](https://mongodb.github.io/ipa/) (IPA). For more details, please refer to the [Spectral’s README.md](tools/spectral/README.md). diff --git a/tools/README.md b/tools/README.md index f99c9414c7..1f5e6971f8 100644 --- a/tools/README.md +++ b/tools/README.md @@ -8,7 +8,7 @@ Includes resources and scripts to generate [MongoDB Atlas Postman Collections](h ## Spectral -MongoDB [Spectral](https://github.com/stoplightio/spectral) OpenAPI specification validation rules +MongoDB [Spectral](https://github.com/stoplightio/spectral) OpenAPI specification validation rules for IPA-compliance. ## CLI diff --git a/tools/spectral/README.md b/tools/spectral/README.md index a183012127..9a728d3781 100644 --- a/tools/spectral/README.md +++ b/tools/spectral/README.md @@ -10,7 +10,10 @@ A set of custom validator rules for the MongoDB Atlas Programmatic API, adhering For a complete list of implemented rules, please refer to the [Ruleset Documentation](./ipa/rulesets/README.md). +### External Documentation + +- Refer to the [IPA Standards](https://mongodb.github.io/ipa/) for specific rules. + ### Internal Documentation -- Refer to the [IPA Standards](http://go/ipa) for specific rules. - Visit the [Spectral Wiki](http://go/openapi-spectral-updates) for additional information. diff --git a/tools/spectral/ipa/README.md b/tools/spectral/ipa/README.md index c67df8465e..92af045faa 100644 --- a/tools/spectral/ipa/README.md +++ b/tools/spectral/ipa/README.md @@ -1,8 +1,6 @@ # IPA Validation -The IPA validation uses [Spectral](https://docs.stoplight.io/docs/spectral/9ffa04e052cc1-spectral-cli) to validate the [MongoDB Atlas Admin API OpenAPI Specification](https://github.com/mongodb/openapi/tree/main/openapi). The rules cover MongoDB best-practices for API design. - -**Note:** For MongoDB engineers, please review https://go/ipa-validation for additional information. +The IPA validation uses [Spectral](https://docs.stoplight.io/docs/spectral/9ffa04e052cc1-spectral-cli) to validate the [MongoDB Atlas Admin API OpenAPI Specification](https://github.com/mongodb/openapi/tree/main/openapi). The rules cover MongoDB's [Improvement Proposal for APIs](https://mongodb.github.io/ipa/) (IPA), which are best-practices for API design. ## Running Locally diff --git a/tools/spectral/ipa/rulesets/IPA-005.yaml b/tools/spectral/ipa/rulesets/IPA-005.yaml index e07a7c93ba..98eda6bf77 100644 --- a/tools/spectral/ipa/rulesets/IPA-005.yaml +++ b/tools/spectral/ipa/rulesets/IPA-005.yaml @@ -1,5 +1,5 @@ # IPA-5: Documenting Exceptions to IPAs -# http://go/ipa/5 +# https://mongodb.github.io/ipa/5 functions: - IPA005ExceptionExtensionFormat diff --git a/tools/spectral/ipa/rulesets/IPA-102.yaml b/tools/spectral/ipa/rulesets/IPA-102.yaml index ba01041905..82cb3ab0e1 100644 --- a/tools/spectral/ipa/rulesets/IPA-102.yaml +++ b/tools/spectral/ipa/rulesets/IPA-102.yaml @@ -1,5 +1,5 @@ # IPA-102: Resource Identifiers -# http://go/ipa/102 +# https://mongodb.github.io/ipa/102 rules: xgen-IPA-102-collection-identifier-camelCase: diff --git a/tools/spectral/ipa/rulesets/IPA-104.yaml b/tools/spectral/ipa/rulesets/IPA-104.yaml index cc63863991..2f44419ea6 100644 --- a/tools/spectral/ipa/rulesets/IPA-104.yaml +++ b/tools/spectral/ipa/rulesets/IPA-104.yaml @@ -1,5 +1,5 @@ # IPA-104: Get -# http://go/ipa/104 +# https://mongodb.github.io/ipa/104 functions: - IPA104EachResourceHasGetMethod diff --git a/tools/spectral/ipa/rulesets/IPA-105.yaml b/tools/spectral/ipa/rulesets/IPA-105.yaml index 9e5ac87c2d..b1f11418e1 100644 --- a/tools/spectral/ipa/rulesets/IPA-105.yaml +++ b/tools/spectral/ipa/rulesets/IPA-105.yaml @@ -1,5 +1,5 @@ # IPA-105: List -# http://go/ipa/105 +# https://mongodb.github.io/ipa/105 functions: - IPA105ListResponseCodeShouldBe200OK diff --git a/tools/spectral/ipa/rulesets/IPA-106.yaml b/tools/spectral/ipa/rulesets/IPA-106.yaml index 4d0be2b13b..5f35d051c3 100644 --- a/tools/spectral/ipa/rulesets/IPA-106.yaml +++ b/tools/spectral/ipa/rulesets/IPA-106.yaml @@ -1,5 +1,5 @@ # IPA-106: Create -# https://mdb.link/mongodb-atlas-openapi-validation# +# https://mongodb.github.io/ipa/106 functions: - IPA106CreateMethodRequestBodyIsRequestSuffixedObject diff --git a/tools/spectral/ipa/rulesets/IPA-107.yaml b/tools/spectral/ipa/rulesets/IPA-107.yaml index eae2d30d91..f4eb6994ff 100644 --- a/tools/spectral/ipa/rulesets/IPA-107.yaml +++ b/tools/spectral/ipa/rulesets/IPA-107.yaml @@ -1,5 +1,5 @@ # IPA-107: Update -# http://go/ipa/107 +# https://mongodb.github.io/ipa/107 functions: - IPA107UpdateMethodMustNotHaveQueryParams diff --git a/tools/spectral/ipa/rulesets/IPA-108.yaml b/tools/spectral/ipa/rulesets/IPA-108.yaml index b0efe908a6..3084e7f29f 100644 --- a/tools/spectral/ipa/rulesets/IPA-108.yaml +++ b/tools/spectral/ipa/rulesets/IPA-108.yaml @@ -1,5 +1,5 @@ # IPA-108: Delete -# http://go/ipa/108 +# https://mongodb.github.io/ipa/108 aliases: DeleteOperationObject: diff --git a/tools/spectral/ipa/rulesets/IPA-109.yaml b/tools/spectral/ipa/rulesets/IPA-109.yaml index 67d7971e74..5658b9c88e 100644 --- a/tools/spectral/ipa/rulesets/IPA-109.yaml +++ b/tools/spectral/ipa/rulesets/IPA-109.yaml @@ -1,5 +1,5 @@ # IPA-109: Custom Methods -# http://go/ipa/109 +# https://mongodb.github.io/ipa/109 functions: - IPA109EachCustomMethodMustBeGetOrPost diff --git a/tools/spectral/ipa/rulesets/IPA-110.yaml b/tools/spectral/ipa/rulesets/IPA-110.yaml index 33ee56d1d8..d1cfee7d3b 100644 --- a/tools/spectral/ipa/rulesets/IPA-110.yaml +++ b/tools/spectral/ipa/rulesets/IPA-110.yaml @@ -1,5 +1,5 @@ # IPA-110: Pagination -# http://go/ipa/110 +# https://mongodb.github.io/ipa/110 functions: - IPA110CollectionsUsePaginatedPrefix diff --git a/tools/spectral/ipa/rulesets/IPA-112.yaml b/tools/spectral/ipa/rulesets/IPA-112.yaml index c923574917..3b1115aae8 100644 --- a/tools/spectral/ipa/rulesets/IPA-112.yaml +++ b/tools/spectral/ipa/rulesets/IPA-112.yaml @@ -1,5 +1,5 @@ # IPA-112: Field Names -# http://go/ipa/112 +# https://mongodb.github.io/ipa/112 functions: - IPA112AvoidProjectFieldNames diff --git a/tools/spectral/ipa/rulesets/IPA-113.yaml b/tools/spectral/ipa/rulesets/IPA-113.yaml index ff26e2f435..07c9c8d1c3 100644 --- a/tools/spectral/ipa/rulesets/IPA-113.yaml +++ b/tools/spectral/ipa/rulesets/IPA-113.yaml @@ -1,5 +1,5 @@ # IPA-113: Singleton Resources -# http://go/ipa/113 +# https://mongodb.github.io/ipa/113 functions: - IPA113SingletonHasNoId diff --git a/tools/spectral/ipa/rulesets/IPA-114.yaml b/tools/spectral/ipa/rulesets/IPA-114.yaml index ec8a5b92b3..1ea526ff3f 100644 --- a/tools/spectral/ipa/rulesets/IPA-114.yaml +++ b/tools/spectral/ipa/rulesets/IPA-114.yaml @@ -1,5 +1,5 @@ # IPA-114: Errors -# http://go/ipa/114 +# https://mongodb.github.io/ipa/114 functions: - IPA114ErrorResponsesReferToApiError diff --git a/tools/spectral/ipa/rulesets/IPA-117.yaml b/tools/spectral/ipa/rulesets/IPA-117.yaml index e23762f6d4..3f7db5bbb4 100644 --- a/tools/spectral/ipa/rulesets/IPA-117.yaml +++ b/tools/spectral/ipa/rulesets/IPA-117.yaml @@ -1,5 +1,5 @@ # IPA-117: Documentation -# http://go/ipa/117 +# https://mongodb.github.io/ipa/117 functions: - IPA117HasDescription diff --git a/tools/spectral/ipa/rulesets/IPA-118.yaml b/tools/spectral/ipa/rulesets/IPA-118.yaml index 78c674863a..ee95e36312 100644 --- a/tools/spectral/ipa/rulesets/IPA-118.yaml +++ b/tools/spectral/ipa/rulesets/IPA-118.yaml @@ -1,5 +1,5 @@ # IPA-118: Extensible by Default -# http://go/ipa/118 +# https://mongodb.github.io/ipa/118 functions: - IPA118NoAdditionalPropertiesFalse diff --git a/tools/spectral/ipa/rulesets/IPA-119.yaml b/tools/spectral/ipa/rulesets/IPA-119.yaml index 83a7c27b72..9a363002ab 100644 --- a/tools/spectral/ipa/rulesets/IPA-119.yaml +++ b/tools/spectral/ipa/rulesets/IPA-119.yaml @@ -1,5 +1,5 @@ # IPA-119: Multi-Cloud Support by Default -# http://go/ipa/119 +# https://mongodb.github.io/ipa/119 functions: - IPA119NoDefaultForCloudProviders diff --git a/tools/spectral/ipa/rulesets/IPA-121.yaml b/tools/spectral/ipa/rulesets/IPA-121.yaml index a1adef5029..b1ede3a36b 100644 --- a/tools/spectral/ipa/rulesets/IPA-121.yaml +++ b/tools/spectral/ipa/rulesets/IPA-121.yaml @@ -1,5 +1,5 @@ # IPA-121: Datetime -# http://go/ipa/121 +# https://mongodb.github.io/ipa/121 functions: - IPA121DateTimeFieldsMentionISO8601 diff --git a/tools/spectral/ipa/rulesets/IPA-123.yaml b/tools/spectral/ipa/rulesets/IPA-123.yaml index 2ac0d1e2f3..e73513a57e 100644 --- a/tools/spectral/ipa/rulesets/IPA-123.yaml +++ b/tools/spectral/ipa/rulesets/IPA-123.yaml @@ -1,5 +1,5 @@ # IPA-123: Enums -# http://go/ipa/123 +# https://mongodb.github.io/ipa/123 functions: - IPA123EachEnumValueMustBeUpperSnakeCase diff --git a/tools/spectral/ipa/rulesets/IPA-124.yaml b/tools/spectral/ipa/rulesets/IPA-124.yaml index a43fd00f57..cd80d0703d 100644 --- a/tools/spectral/ipa/rulesets/IPA-124.yaml +++ b/tools/spectral/ipa/rulesets/IPA-124.yaml @@ -1,5 +1,5 @@ # IPA-124: Repeated Fields -# http://go/ipa/124 +# https://mongodb.github.io/ipa/124 functions: - IPA124ArrayMaxItems diff --git a/tools/spectral/ipa/rulesets/IPA-125.yaml b/tools/spectral/ipa/rulesets/IPA-125.yaml index 35241acf4e..21ef3be6e5 100644 --- a/tools/spectral/ipa/rulesets/IPA-125.yaml +++ b/tools/spectral/ipa/rulesets/IPA-125.yaml @@ -1,5 +1,5 @@ # IPA-125: Single Type in Request and Response -# http://go/ipa/125 +# https://mongodb.github.io/ipa/125 functions: - IPA125OneOfMustHaveDiscriminator diff --git a/tools/spectral/ipa/rulesets/IPA-126.yaml b/tools/spectral/ipa/rulesets/IPA-126.yaml index f11f37cc28..7ad68e7e1a 100644 --- a/tools/spectral/ipa/rulesets/IPA-126.yaml +++ b/tools/spectral/ipa/rulesets/IPA-126.yaml @@ -1,5 +1,5 @@ # IPA-126: Top-Level API Names -# http://go/ipa/126 +# https://mongodb.github.io/ipa/126 functions: - IPA126TagNamesShouldUseTitleCase diff --git a/tools/spectral/ipa/rulesets/README.md b/tools/spectral/ipa/rulesets/README.md index 3112cde4dc..4ebb16eefc 100644 --- a/tools/spectral/ipa/rulesets/README.md +++ b/tools/spectral/ipa/rulesets/README.md @@ -10,7 +10,7 @@ Below is a list of all available rules, their descriptions and severity levels. ### IPA-005 -Rules are based on [http://go/ipa/IPA-5](http://go/ipa/IPA-5). +Rules are based on [https://mongodb.github.io/ipa/5](https://mongodb.github.io/ipa/5). #### xgen-IPA-005-exception-extension-format @@ -27,7 +27,7 @@ Rule checks for the following conditions: ### IPA-102 -Rules are based on [http://go/ipa/IPA-102](http://go/ipa/IPA-102). +Rules are based on [https://mongodb.github.io/ipa/102](https://mongodb.github.io/ipa/102). #### xgen-IPA-102-collection-identifier-camelCase @@ -76,7 +76,7 @@ Rule checks for the following conditions: ### IPA-104 -Rules are based on [http://go/ipa/IPA-104](http://go/ipa/IPA-104). +Rules are based on [https://mongodb.github.io/ipa/104](https://mongodb.github.io/ipa/104). #### xgen-IPA-104-resource-has-GET @@ -143,7 +143,7 @@ Rule checks for the following conditions: ### IPA-105 -Rules are based on [http://go/ipa/IPA-105](http://go/ipa/IPA-105). +Rules are based on [https://mongodb.github.io/ipa/105](https://mongodb.github.io/ipa/105). #### xgen-IPA-105-list-method-response-code-is-200 @@ -197,7 +197,7 @@ The response body of the List method should consist of the same resource object ### IPA-106 -Rules are based on [http://go/ipa/IPA-106](http://go/ipa/IPA-106). +Rules are based on [https://mongodb.github.io/ipa/106](https://mongodb.github.io/ipa/106). #### xgen-IPA-106-create-method-request-body-is-request-suffixed-object @@ -277,7 +277,7 @@ Rule checks for the following conditions: ### IPA-107 -Rules are based on [http://go/ipa/IPA-107](http://go/ipa/IPA-107). +Rules are based on [https://mongodb.github.io/ipa/107](https://mongodb.github.io/ipa/107). #### xgen-IPA-107-update-must-not-have-query-params @@ -348,7 +348,7 @@ Rule checks for the following conditions: ### IPA-108 -Rules are based on [http://go/ipa/IPA-108](http://go/ipa/IPA-108). +Rules are based on [https://mongodb.github.io/ipa/108](https://mongodb.github.io/ipa/108). #### xgen-IPA-108-delete-response-should-be-empty @@ -392,7 +392,7 @@ Rule checks for the following conditions: ### IPA-109 -Rules are based on [http://go/ipa/IPA-109](http://go/ipa/IPA-109). +Rules are based on [https://mongodb.github.io/ipa/109](https://mongodb.github.io/ipa/109). #### xgen-IPA-109-custom-method-must-be-GET-or-POST @@ -437,7 +437,7 @@ Rule checks for the following conditions: ### IPA-110 -Rules are based on [http://go/ipa/IPA-110](http://go/ipa/IPA-110). +Rules are based on [https://mongodb.github.io/ipa/110](https://mongodb.github.io/ipa/110). #### xgen-IPA-110-collections-use-paginated-prefix @@ -513,7 +513,7 @@ Rule checks for the following conditions: ### IPA-112 -Rules are based on [http://go/ipa/IPA-112](http://go/ipa/IPA-112). +Rules are based on [https://mongodb.github.io/ipa/112](https://mongodb.github.io/ipa/112). #### xgen-IPA-112-avoid-project-field-names @@ -554,7 +554,7 @@ Rule checks for the following conditions: ### IPA-113 -Rules are based on [http://go/ipa/IPA-113](http://go/ipa/IPA-113). +Rules are based on [https://mongodb.github.io/ipa/113](https://mongodb.github.io/ipa/113). #### xgen-IPA-113-singleton-must-not-have-id @@ -593,7 +593,7 @@ Rule checks for the following conditions: ### IPA-114 -Rules are based on [http://go/ipa/IPA-114](http://go/ipa/IPA-114). +Rules are based on [https://mongodb.github.io/ipa/114](https://mongodb.github.io/ipa/114). #### xgen-IPA-114-error-responses-refer-to-api-error @@ -638,7 +638,7 @@ is not found. ### IPA-117 -Rules are based on [http://go/ipa/IPA-117](http://go/ipa/IPA-117). +Rules are based on [https://mongodb.github.io/ipa/117](https://mongodb.github.io/ipa/117). #### xgen-IPA-117-description @@ -774,7 +774,7 @@ The rule checks for the presence of the `schema`, `examples` or `example` proper ### IPA-118 -Rules are based on [http://go/ipa/IPA-118](http://go/ipa/IPA-118). +Rules are based on [https://mongodb.github.io/ipa/118](https://mongodb.github.io/ipa/118). #### xgen-IPA-118-no-additional-properties-false @@ -790,7 +790,7 @@ This rule checks all nested schemas, but only parent schemas can be marked for e ### IPA-119 -Rules are based on [http://go/ipa/IPA-119](http://go/ipa/IPA-119). +Rules are based on [https://mongodb.github.io/ipa/119](https://mongodb.github.io/ipa/119). #### xgen-IPA-119-no-default-for-cloud-providers @@ -804,7 +804,7 @@ All cloudProviderEnumValues should be listed in the enum array. ### IPA-121 -Rules are based on [http://go/ipa/IPA-121](http://go/ipa/IPA-121). +Rules are based on [https://mongodb.github.io/ipa/121](https://mongodb.github.io/ipa/121). #### xgen-IPA-121-date-time-fields-mention-iso-8601 @@ -816,7 +816,7 @@ It collects adoption metrics at schema property level and parameter level ### IPA-123 -Rules are based on [http://go/ipa/IPA-123](http://go/ipa/IPA-123). +Rules are based on [https://mongodb.github.io/ipa/123](https://mongodb.github.io/ipa/123). #### xgen-IPA-123-enum-values-must-be-upper-snake-case @@ -847,7 +847,7 @@ Rule checks for the following conditions: ### IPA-124 -Rules are based on [http://go/ipa/IPA-124](http://go/ipa/IPA-124). +Rules are based on [https://mongodb.github.io/ipa/124](https://mongodb.github.io/ipa/124). #### xgen-IPA-124-array-max-items @@ -868,7 +868,7 @@ Rule checks for the following conditions: ### IPA-125 -Rules are based on [http://go/ipa/IPA-125](http://go/ipa/IPA-125). +Rules are based on [https://mongodb.github.io/ipa/125](https://mongodb.github.io/ipa/125). #### xgen-IPA-125-oneOf-must-have-discriminator @@ -922,7 +922,7 @@ object types with clear discriminators. ### IPA-126 -Rules are based on [http://go/ipa/IPA-126](http://go/ipa/IPA-126). +Rules are based on [https://mongodb.github.io/ipa/126](https://mongodb.github.io/ipa/126). #### xgen-IPA-126-tag-names-should-use-title-case diff --git a/tools/spectral/ipa/scripts/generateRulesetReadme.js b/tools/spectral/ipa/scripts/generateRulesetReadme.js index c74d6c0574..560f5a8917 100644 --- a/tools/spectral/ipa/scripts/generateRulesetReadme.js +++ b/tools/spectral/ipa/scripts/generateRulesetReadme.js @@ -102,8 +102,7 @@ function getIpaRulesetUrl(ipaNumber) { if (parts.length > 1) { parts[1] = parts[1].replace(/^0+/, ''); } - const ipaNumberFormatted = parts.join('-'); - return `[http://go/ipa/${ipaNumberFormatted}](http://go/ipa/${ipaNumberFormatted})`; + return `[https://mongodb.github.io/ipa/${parts[1]}](https://mongodb.github.io/ipa/${parts[1]})`; } function filterRulesByIpaNumber(ipaNumber, rules) {