Basic work for generating.

packages/server/package.json

@@ -3,7 +3,7 @@
   "email": "hi@budibase.com",
   "version": "0.9.190-alpha.0",
   "description": "Budibase Web Server",
-  "main": "src/index.js",
+  "main": "src/index.ts",
   "repository": {
     "type": "git",
     "url": "https://github.com/Budibase/budibase.git"
@@ -130,6 +130,7 @@
     "@babel/preset-env": "^7.14.4",
     "@budibase/standard-components": "^0.9.139",
     "@jest/test-sequencer": "^24.8.0",
+    "@types/apidoc": "^0.50.0",
     "@types/bull": "^3.15.1",
     "@types/jest": "^26.0.23",
     "@types/koa": "^2.13.3",
@@ -137,6 +138,7 @@
     "@types/node": "^15.12.4",
     "@types/oracledb": "^5.2.1",
     "@typescript-eslint/parser": "4.28.0",
+    "apidoc": "^0.50.2",
     "babel-jest": "^27.0.2",
     "copyfiles": "^2.4.1",
     "docker-compose": "^0.23.6",

packages/server/scripts/docs/generate.js

@@ -0,0 +1,59 @@
+const fs = require("fs")
+const { join } = require("path")
+const { createDoc } = require("apidoc")
+const packageJson = require("../../package.json")
+
+const config = {
+  name: "Budibase API",
+  version: packageJson.version,
+  description:
+    "Documentation for the various API endpoints of the Budibase backend.",
+  title: "Budibase app service API",
+}
+
+const disallowed = []
+
+function filter(parsedRouteFiles) {
+  const tagToSearch = "url"
+  for (let routeFile of parsedRouteFiles) {
+    for (let route of routeFile) {
+      let routeInfo = route["local"]
+      if (disallowed.includes(routeInfo[tagToSearch])) {
+        const idx = routeFile.indexOf(route)
+        routeFile.splice(idx, 1)
+      }
+    }
+  }
+}
+
+function generate() {
+  // start by writing a config file
+  const configPath = join(__dirname, "config.json")
+  fs.writeFileSync(configPath, JSON.stringify(config))
+  const mainPath = join(__dirname, "..", "..")
+  const srcPath = join(mainPath, "src", "api", "routes")
+  const assetsPath = join(mainPath, "builder", "assets", "docs")
+  if (!fs.existsSync(assetsPath)) {
+    fs.mkdirSync(assetsPath, { recursive: true })
+  }
+  const doc = createDoc({
+    src: srcPath,
+    dest: assetsPath,
+    silent: true,
+    filters: {
+      main: {
+        postFilter: filter,
+      },
+    },
+    config: configPath,
+  })
+  if (typeof doc !== "boolean") {
+    console.log("Docs generated successfully.")
+  } else {
+    console.error("Unable to generate docs.")
+  }
+  // delete the temporary config file
+  fs.unlinkSync(configPath)
+}
+
+generate()

packages/server/src/api/routes/row.js

@@ -14,24 +14,80 @@ const {
 const router = Router()
 
 router
+  /**
+   * @api {get} /api/:tableId/:rowId/enrich Get an enriched row
+   * @apiName /api/:tableId/:rowId/enrich
+   * @apiGroup rows
+   * @apiPermission table read access
+   * @apiDescription This API is only useful when dealing with rows that have relationships.
+   * Normally when a row is a returned from the API relationships will only have the structure
+   * `{ primaryDisplay: "name", _id: ... }` but this call will return the full related rows
+   * for each relationship instead.
+   *
+   * @apiParam {string} rowId The ID of the row which is to be retrieved and enriched.
+   *
+   * @apiSuccess {object} row The response body will be the enriched row.
+   * @apiError {string} message If the table or row could not be found then an error will be thrown.
+   */
   .get(
     "/api/:tableId/:rowId/enrich",
     paramSubResource("tableId", "rowId"),
     authorized(PermissionTypes.TABLE, PermissionLevels.READ),
     rowController.fetchEnrichedRow
   )
+  /**
+   * @api {get} /api/:tableId/rows Get all rows in a table
+   * @apiName /api/:tableId/rows
+   * @apiGroup rows
+   * @apiPermission table read access
+   * @apiDescription This is a deprecated endpoint that should not be used anymore, instead use the search endpoint.
+   * This endpoint gets all of the rows within the specified table - it is not heavily used
+   * due to its lack of support for pagination. With SQL tables this will retrieve up to a limit and then
+   * will simply stop.
+   *
+   * @apiParam {string} tableId The ID of the table to retrieve all rows within.
+   *
+   * @apiSuccess {object[]} rows The response body will be an array of all rows found.
+   * @apiError {string} message If the table could not be found then an error will be thrown.
+   */
   .get(
     "/api/:tableId/rows",
     paramResource("tableId"),
     authorized(PermissionTypes.TABLE, PermissionLevels.READ),
     rowController.fetch
   )
+  /**
+   * @api {get} /api/:tableId/rows/:rowId Retrieve a single row
+   * @apiName /api/:tableId/rows/:rowId
+   * @apiGroup rows
+   * @apiPermission table read access
+   * @apiDescription This endpoint retrieves only the specified row. If you wish to retrieve
+   * a row by anything other than its _id field, use the search endpoint.
+   *
+   * @apiParam {string} tableId The ID of the table to retrieve a row from.
+   * @apiParam {string} rowId The ID of the row to retrieve.
+   *
+   * @apiSuccess {object} row The response body will be the row that was found.
+   * @apiError {string} message If the table or row could not be found then an error will be thrown.
+   */
   .get(
     "/api/:tableId/rows/:rowId",
     paramSubResource("tableId", "rowId"),
     authorized(PermissionTypes.TABLE, PermissionLevels.READ),
     rowController.find
   )
+  /**
+   * @api {post} /api/:tableId/search Search for rows in a table
+   * @apiName /api/:tableId/search
+   * @apiGroup rows
+   * @apiPermission table read access
+   * @apiDescription This is the primary method of accessing rows in Budibase, the data provider
+   * and data UI in the builder are built atop this. All filtering, sorting and pagination is
+   * handled through this, for internal and external (datasource plus, e.g. SQL) tables.
+   *
+   * @apiBody
+   *
+   */
   .post(
     "/api/:tableId/search",
     paramResource("tableId"),