Add sorting decorators (like old Redoc had) (#38)

* adopt the tag sorting, add method sorting (no docs yet)

* Add sorting decorators for properties, operatiosns and enums

* Remove the operation sort, cannot separate operations within a pathItem

* Add information about the available sorting options

* Better formatting

* Update custom-plugin-decorators/sorting/sort-methods.js

Co-authored-by: Andrew Tatomyr <[email protected]>

* fix a syntax problem

* Adopt updated plugin format

* Add configuration to the method sorting decorator

* Add a rule for checking method sort order

* Make the method sorting rule configurable

* Add alphabetical property sorting, update README and config files

* Sort out formatting for code and words

* set a more expected default order for methods

* Apply suggestions from code review

Co-authored-by: Adam Altman <[email protected]>

* Move sorting to be a top-level plugin, add index page listing

---------

Co-authored-by: Andrew Tatomyr <[email protected]>
Co-authored-by: Adam Altman <[email protected]>

Author: 3 people

README.md

@@ -51,6 +51,8 @@ There are some fantastic examples of [configurable rules](https://redocly.com/do
 
 The [custom plugin](https://redocly.com/docs/cli/custom-plugins/) is the ultimate in extensibility, but it's an advanced feature. Try these plugins for inspiration and to get you started. Rather than including the whole plugin, there are also sections for individual rules and decorators further down.
 
+- [Sorting plugin](./custom-plugins/sorting) - rules to check sort order and decorators to transform an API description into the correct order. Includes sorting for tags, methods, properties and enum values.
+
 #### Decorators (for custom plugins)
 
 - [Tag sorting](./custom-plugin-decorators/tag-sorting) - put your tags list in alphabetical order.

custom-plugins/sorting/README.md

@@ -0,0 +1,130 @@
+# A suite of sorting decorators
+
+Authors:
+
+- [`@lornajane`](https://github.com/lornajane), Lorna Mitchell (Redocly)
+
+## What this does and why
+
+There are lots of reasons that you'd want to alter the order of the items in your API description, such as putting required fields first, or just ordering things alphabetically (or logically!) to make things consistent and easier to find.
+When Redocly only made API documentation tools, the sorting changes were made as part of the docs build.
+But now we make more complex tools, and many API pipelines have more than just docs in them too - so these operations are more commonly done with a decorator to transform the API description; then it can be used with any tools.
+
+Redocly CLI has a [`tags-alphabetical`](https://redocly.com/docs/cli/rules/tags-alphabetical) rule to error if the `tags` section isn't in alphabetical order by `name`.
+This plugin adds some additional *rules* for checking sort orders.
+
+- `method-sort` rule to put your methods in the desired order. The default is `["post", "patch", "put", "get", "delete"]`, but you can supply your own with an `order` parameter.
+- `property-sort` rule to sort properties either alphabetically with `order: alpha` (the default sort order for this rule) or with `order: required` to put the required properties first.
+
+The plugin also includes *decorators* to sort your OpenAPI descriptions, perhaps to allow an existing OpenAPI description to be easily updated to meet the expectations of the sorting rules.
+Here's a full list of the sorting features:
+
+- `methods`: sorts methods consistently in the order you supply (or `GET`, `POST`, `PUT`, `PATCH` and `DELETE` by default), with any unsorted methods appended afterwards
+- `enums-alphabetical`: sorts the options for an enum field alphabetically
+- `properties-alphabetical`: sorts object properties in schemas alphabetically
+- `properties-required-first`: puts the required properties at the top of the list (run this *after* any other property sorting decorators)
+- `tags-alphabetical`: sorts tags alphabetically
+
+## Code
+
+Here's the main plugin entrypoint, it's in `sorting.js`:
+
+```javascript
+const SortTagsAlphabetically = require("./sort-tags");
+const SortEnumsAlphabetically = require("./sort-enums");
+const SortMethods = require("./sort-methods");
+const SortPropertiesAlphabetically = require("./sort-props-alpha");
+const SortPropertiesRequiredFirst = require("./sort-props-required");
+const RuleSortMethods = require("./rule-sort-methods");
+const RuleSortProps = require("./rule-sort-props");
+
+module.exports = function Sorting() {
+  return {
+    id: "sorting",
+    rules: {
+      oas3: {
+        "method-sort": RuleSortMethods,
+        "property-sort": RuleSortProps,
+      },
+    },
+    decorators: {
+      oas3: {
+        "tags-alphabetical": SortTagsAlphabetically,
+        "enums-alphabetical": SortEnumsAlphabetically,
+        methods: SortMethods,
+        "properties-alphabetical": SortPropertiesAlphabetically,
+        "properties-required-first": SortPropertiesRequiredFirst,
+      },
+    },
+  };
+};
+```
+
+Each of the available rules/decorators is in its own file, rather than copying them here, you can view them in the same directory as this `README`:
+
+- [rule-sort-methods.js](./rule-sort-methods.js)
+- [rule-sort-props.js](./rule-sort-props.js)
+- [sort-tags.js](./sort-tags.js)
+- [sort-enums.js](./sort-enums.js)
+- [sort-methods.js](./sort-methods.js)
+- [sort-props-alpha.js](./sort-props-alpha.js)
+- [sort-props-required.js](./sort-props-required.js)
+
+You can copy or adapt the plugins here to meet your own needs, changing the sorting algorithms or sorting different fields.
+One thing to look out for is that if you need to re-order the properties of an object, then you should visit the parent of the object, and assign the new object to the key that should be updated.
+
+## Examples
+
+Add the plugin to `redocly.yaml` and enable the decorators and/or rules:
+
+```yaml
+plugins:
+  - sorting.js
+
+decorators:
+  sorting/methods: on
+    order: [delete, get]
+  sorting/tags-alphabetical: on
+  sorting/enums-alphabetical: on
+  sorting/properties-alphabetical: on
+  sorting/properties-required-first: on
+
+rules:
+  sorting/method-sort:
+    severity: error
+    order: [get, post, delete]
+  sorting/property-sort:
+    severity: warn
+    type: required # default is alpha
+
+```
+
+### Lint with rules
+
+Run the [lint command](https://redocly.com/docs/cli/commands/lint) and the rules are used during linting.
+Your command will look something like the following example:
+
+```bash
+redocly lint openapi.yaml
+```
+
+If your OpenAPI doesn't fulfil the criteria in the configured rules, the details of the warnings/errors are shown in the output.
+
+Adjust the rule configuration or severity levels to meet your needs, and let us know if there's some other rules you'd like to see included.
+
+### Bundle with decorators
+
+Run the [bundle command](https://redocly.com/docs/cli/commands/bundle) and the decorators are applied during bundling.
+Your command will look something like the following example:
+
+```bash
+redocly bundle openapi.yaml -o updated-openapi.yaml
+```
+
+Use your favorite "diff" tool to look at the changes made between your existing API description and the updated version.
+
+Remove or turn off any of the decorators that don't fit your use case, and let us know if there are any other sorting features you need by opening an issue on this repository.
+
+## References
+
+- [`tags-alphabetical' rule](https://redocly.com/docs/cli/rules/tags-alphabetical)

custom-plugins/sorting/redocly.yaml

@@ -0,0 +1,20 @@
+plugins:
+  - sorting.js
+
+rules:
+  sorting/method-sort: 
+    severity: error
+    order: [get, post, delete]
+  sorting/property-sort:
+    severity: warn
+    type: required
+
+decorators:
+  sorting/properties-alphabetical: on
+  sorting/tags-alphabetical: on
+  sorting/methods:
+    order: [get, post, delete]
+  sorting/enums-alphabetical: on
+  sorting/properties-required-first: on
+
+

custom-plugins/sorting/rule-sort-methods.js

@@ -0,0 +1,36 @@
+function RuleSortMethods({ order }) {
+  console.log("check method order");
+  return {
+    PathItem: {
+      enter(pathItem, ctx) {
+        // default method sort order, can be changed with an "order" param in config
+        let methodOrder = ["post", "patch", "put", "get", "delete"];
+        if (order) {
+          methodOrder = order;
+        }
+
+        // Identify the methods that are present and put them in order
+        const methods = Object.getOwnPropertyNames(pathItem);
+        const expectedOrder = methodOrder.filter((item) =>
+          methods.includes(item)
+        );
+
+        i = 0;
+        while (i < expectedOrder.length) {
+          // if this method is in the array, it must be in the expected order
+          if (
+            expectedOrder.includes(methods[i]) &&
+            methods[i] !== expectedOrder[i]
+          ) {
+            ctx.report({
+              message: `Unexpected method order, expected ${expectedOrder[i]} but found ${methods[i]}`,
+            });
+          }
+          i++;
+        }
+      },
+    },
+  };
+}
+
+module.exports = RuleSortMethods;

custom-plugins/sorting/rule-sort-props.js

@@ -0,0 +1,72 @@
+function RuleSortProps({ type }) {
+  let sortType = "alpha"; // default
+  const supportedSortTypes = ["alpha", "required"];
+  if (type && supportedSortTypes.includes(type)) {
+    sortType = type;
+  }
+  console.log(`check properties order (${sortType})`);
+  return {
+    Schema: {
+      enter(schema, ctx) {
+        if (schema.type == "object") {
+          const propList = Object.getOwnPropertyNames(schema.properties);
+
+          if (sortType == "required") {
+            // exit early if there are no required properties
+            let requiredList = [];
+            if (!schema.required) {
+              return;
+            } else {
+              requiredList = schema.required;
+            }
+
+            const notRequiredList = propList.filter(
+              (item) => !requiredList.includes(item)
+            );
+            // if the notRequiredList is empty, everything was required, we can exit
+            if (notRequiredList.length == 0) {
+              return;
+            }
+
+            // loop through, if we find an optional field before a required one then report
+            let required = true;
+            let prevProp = "";
+            let prevReq = true;
+            propList.forEach((prop) => {
+              const isReq = requiredList.includes(prop);
+              // did we go from an optional field to a required one?
+              if (isReq && !prevReq) {
+                ctx.report({
+                  message: `Unexpected property order, found required \`${prop}\` after optional \`${prevProp}\``,
+                });
+              }
+
+              // need these to refer to on the next iteration
+              prevReq = isReq;
+              prevProp = prop;
+            });
+          } else {
+            // alpha sort is default
+            const sortedList = [...propList].sort();
+
+            // use a loop so we can show exactly where the order failed for large objects
+            let i = 0;
+
+            while (i < propList.length) {
+              if (sortedList[i] !== propList[i]) {
+                ctx.report({
+                  message: `Unexpected property order, found \`${propList[i]}\` but expected \`${sortedList[i]}\``,
+                });
+                return; // if one property is out of order, there might be many others, return to avoid noise
+              }
+
+              i++;
+            }
+          }
+        }
+      },
+    },
+  };
+}
+
+module.exports = RuleSortProps;

custom-plugins/sorting/sort-enums.js

@@ -0,0 +1,14 @@
+module.exports = SortEnumsAlphabetically;
+
+function SortEnumsAlphabetically() {
+  console.log("re-ordering enums: alphabetical");
+  return {
+    Schema: {
+      leave(target) {
+        if (target.enum) {
+          target.enum.sort();
+        }
+      },
+    },
+  };
+}

custom-plugins/sorting/sort-methods.js

@@ -0,0 +1,39 @@
+module.exports = SortMethods;
+
+function SortMethods({ order }) {
+  console.log("re-ordering methods");
+  return {
+    PathItem: {
+      leave(pathItem) {
+        // start with the default ordering, override with config if we have it
+        let methodList = ["get", "post", "patch", "put", "delete"];
+        if (order) {
+          methodList = order;
+        }
+
+        let existingMethods = Object.getOwnPropertyNames(pathItem);
+
+        for (const method of methodList) {
+          const operation = pathItem[method];
+          // For each defined operation, delete it and re-add it to the path so they will be in the correct order:
+          if (operation) {
+            // remove it from the methods list so we know we processed it
+            existingMethods = existingMethods.filter((x) => x != method);
+            delete pathItem[method];
+            pathItem[method] = operation;
+          }
+        }
+
+        // now re-add any methods that weren't in the list
+        for (const method of existingMethods) {
+          const operation = pathItem[method];
+          // Delete and re-add unprocessed operations to the path so they will be in the correct order:
+          if (operation) {
+            delete pathItem[method];
+            pathItem[method] = operation;
+          }
+        }
+      },
+    },
+  };
+}

custom-plugins/sorting/sort-props-alpha.js

@@ -0,0 +1,21 @@
+module.exports = SortPropertiesAlphabetically;
+
+function SortPropertiesAlphabetically() {
+  console.log("re-ordering properties: alphabetical");
+  return {
+    Schema: {
+      leave(schema) {
+        if (schema.type == "object") {
+          const propList = Object.getOwnPropertyNames(schema.properties).sort();
+          let newProps = {};
+
+          propList.forEach((prop) => {
+            newProps[prop] = schema.properties[prop];
+          });
+
+          schema.properties = newProps;
+        }
+      },
+    },
+  };
+}

custom-plugins/sorting/sort-props-required.js

@@ -0,0 +1,31 @@
+module.exports = SortPropertiesRequiredFirst;
+
+function SortPropertiesRequiredFirst() {
+  console.log("re-ordering properties: required first");
+  return {
+    Schema: {
+      leave(schema) {
+        if (schema.type == "object") {
+          const propList = Object.getOwnPropertyNames(schema.properties);
+          let newProps = {};
+
+          if (schema.required && schema.required.length > 0) {
+            const requiredList = schema.required;
+            // put the required items in first
+            requiredList.forEach((prop) => {
+              newProps[prop] = schema.properties[prop];
+            });
+
+            // now add anything that wasn't already added
+            propList.forEach((prop) => {
+              if (!newProps[prop]) {
+                newProps[prop] = schema.properties[prop];
+              }
+            });
+            schema.properties = newProps;
+          }
+        }
+      },
+    },
+  };
+}

custom-plugins/sorting/sort-tags.js

@@ -0,0 +1,16 @@
+module.exports = SortTagsAlphabetically;
+
+function SortTagsAlphabetically() {
+  console.log("re-ordering tags: alphabetical");
+  return {
+    TagList: {
+      leave(target) {
+        target.sort((a, b) => {
+          if (a.name < b.name) {
+            return -1;
+          }
+        });
+      },
+    },
+  };
+}