From 6eed248836d4975f53629e0572958a9dc27f9ae7 Mon Sep 17 00:00:00 2001
From: confused-Techie <dev@lhbasics.com>
Date: Thu, 14 Sep 2023 00:47:37 -0700
Subject: [PATCH] Even better docs. Use the `endpoint.params` object to get
 details of parameters from the `parameters` folder

---
 .../resources/refactor-DONT_KEEP_THIS_FILE.md | 10 ++++
 src/controllers/getPackagesSearch.js          | 49 +------------------
 src/parameters/direction.js                   | 15 ++++++
 src/parameters/page.js                        | 12 +++++
 src/parameters/query.js                       | 10 ++++
 src/parameters/sort.js                        | 18 +++++++
 6 files changed, 66 insertions(+), 48 deletions(-)
 create mode 100644 src/parameters/direction.js
 create mode 100644 src/parameters/page.js
 create mode 100644 src/parameters/query.js
 create mode 100644 src/parameters/sort.js

diff --git a/docs/resources/refactor-DONT_KEEP_THIS_FILE.md b/docs/resources/refactor-DONT_KEEP_THIS_FILE.md
index 2ded9c95..9c7b0e44 100644
--- a/docs/resources/refactor-DONT_KEEP_THIS_FILE.md
+++ b/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.
diff --git a/src/controllers/getPackagesSearch.js b/src/controllers/getPackagesSearch.js
index cbf6542f..5c1d91c3 100644
--- a/src/controllers/getPackagesSearch.js
+++ b/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",
diff --git a/src/parameters/direction.js b/src/parameters/direction.js
new file mode 100644
index 00000000..a2ae641e
--- /dev/null
+++ b/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."
+};
diff --git a/src/parameters/page.js b/src/parameters/page.js
new file mode 100644
index 00000000..86ae65c3
--- /dev/null
+++ b/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."
+};
diff --git a/src/parameters/query.js b/src/parameters/query.js
new file mode 100644
index 00000000..ab80a63d
--- /dev/null
+++ b/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."
+};
diff --git a/src/parameters/sort.js b/src/parameters/sort.js
new file mode 100644
index 00000000..8f5509e6
--- /dev/null
+++ b/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."
+};