Even better docs. Use the endpoint.params object to get details of …

…parameters from the `parameters` folder

docs/resources/refactor-DONT_KEEP_THIS_FILE.md

@@ -63,3 +63,13 @@ Meaning the only tests we would likely need are:
 I think this is plenty to focus on now. At the very least the changes described here would likely mean a rewrite of about or over half the entire codebase. But if all goes to plan, would mean that every single piece of logic is more modular, keeping logic related to itself within the same file, and if tests are effected as hoped, would mean a much more robust testing solution, that who knows, may actually be able to achieve near 100% testing coverage.
 
 One side effect of all this change, means the possibility of generating documentation of the API based totally on the documentation itself, where we no longer would be reliant on my own `@confused-techie/quick-webserver-docs` module, nor having to ensure comments are updated.
+
+## Documentation
+
+Alright, so some cool ideas about documentation.
+
+Within `./src/parameters` we have modules named after the common name of any given parameter.
+
+Then to ensure our OpenAPI docs are ALWAYS up to date with the actual code, we take the `params` object of every single endpoint module, and we actually iterate through the `params` there and match those against these modules within `parameters`.
+
+So that the parameters within our docs will always match exactly with what's actually used. This does mean the name we use for the parameter within code has to match up with the names of the files.

src/controllers/getPackagesSearch.js

@@ -1,53 +1,6 @@
 module.exports = {
   docs: {
-    parameters: [
-      {
-        name: "q",
-        in: "query",
-        schema: { type: "string" },
-        example: "generic-lsp",
-        required: true,
-        description: "Search query."
-      },
-      {
-        name: "page",
-        in: "query",
-        schema: { type: "number", minimum: 1, default: 1 },
-        example: 1,
-        allowEmptyValue: true,
-        description: "The page of search results to return."
-      },
-      {
-        name: "sort",
-        in: "query",
-        schema: {
-          type: "string",
-          enum: [
-            "downloads",
-            "created_at",
-            "updated_at",
-            "stars",
-            "relevance"
-          ],
-          default: "relevance"
-        },
-        example: "downloads",
-        allowEmptyValue: true,
-        description: "Method to sort the results."
-      },
-      {
-        name: "direction",
-        in: "query",
-        schema: {
-          type: "string",
-          enum: [ "desc", "asc" ],
-          default: "desc"
-        },
-        example: "desc",
-        allowEmptyValue: true,
-        description: "Direction to list search results."
-      }
-    ]
+
   },
   endpoint: {
     method: "GET",

src/parameters/direction.js

@@ -0,0 +1,15 @@
+module.exports = {
+  name: "direction",
+  in: "query",
+  schema: {
+    type: "string",
+    enum: [
+      "desc",
+      "asc"
+    ],
+    default: "desc"
+  },
+  example: "desc",
+  allowEmptyValue: true,
+  description: "Direction to list search results."
+};

src/parameters/page.js

@@ -0,0 +1,12 @@
+module.exports = {
+  name: "page",
+  in: "query",
+  schema: {
+    type: "number",
+    minimum: 1,
+    default: 1
+  },
+  example: 1,
+  allowEmptyValue: true,
+  description: "The page of available results to return."
+};

src/parameters/query.js

@@ -0,0 +1,10 @@
+module.exports = {
+  name: "q",
+  in: "query",
+  schema: {
+    type: "string"
+  },
+  example: "generic-lsp",
+  required: true,
+  description: "Search query."
+};

src/parameters/sort.js

@@ -0,0 +1,18 @@
+module.exports = {
+  name: "sort",
+  in: "query",
+  schema: {
+    type: "string",
+    enum: [
+      "downloads",
+      "created_at",
+      "updated_at",
+      "stars",
+      "relevance"
+    ],
+    default: "relevance"
+  },
+  example: "downloads",
+  allowEmptyValue: true,
+  description: "Method to sort the results."
+};