Add API docs

Author: Kevin Richter

.github/ISSUE_TEMPLATE.md

@@ -3,13 +3,53 @@
   "version": "1.0.0",
   "scripts": {
     "copy-pages": "cp pages/* source/",
-    "compile-docs-wrapper": "npx esdoc -c config/esdoc-wrapper.json"
+    "compile-docs-wrapper": "npx esdoc"
   },
   "dependencies": {
     "@mapcreator/maps4news": "^1.4.22",
     "esdoc": "^1.1.0",
     "esdoc-ecmascript-proposal-plugin": "^1.0.0",
     "esdoc-standard-plugin": "^1.0.0",
     "swagger-ui": "^3.18.1"
+  },
+  "esdoc": {
+    "name": "maps4news",
+    "index": "./node_modules/@mapcreator/maps4news/README.md",
+    "source": "./node_modules/@mapcreator/maps4news/src",
+    "destination": "./source/wrapper",
+    "plugins": [
+      {
+        "name": "esdoc-standard-plugin",
+        "option": {
+          "accessor": {
+            "access": [
+              "public",
+              "protected"
+            ],
+            "autoPrivate": true
+          },
+          "undocumentIdentifier": {
+            "enable": true
+          },
+          "unexportedIdentifier": {
+            "enable": false
+          },
+          "typeInference": {
+            "enable": true
+          },
+          "brand": {
+            "title": "Maps4News Api Wrapper",
+            "description": "Maps4News Api Javascript Wrapper"
+          }
+        }
+      },
+      {
+        "name": "esdoc-ecmascript-proposal-plugin",
+        "option": {
+          "all": true
+        }
+      }
+    ]
   }
+
 }

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,118 @@
+# Introduction
+
+...
+
+
+# Return Data
+
+> For Success Responses
+
+```json
+{
+  "success": true,
+  "data": {}
+}
+```
+
+> For Error Responses
+
+```json
+{
+  "success": false,
+  "error": {
+    "type": "HttpNotFoundException",
+    "message": "Page Not Found"
+  }
+}
+```
+
+All JSON responses from the API a wrapper in a base object.
+
+Be sure to include an `Accept: application/json` header, otherwise errors like `401, 403 & 404` will either return HTML or redirect you to the login page.
+
+
+# Query Parameters
+
+The API has a few query parameters available that you can use to help find the resources you need.
+
+All three of these query parameters are only available on listing endpoints, so endpoints that return an array of items.
+
+## Pagination
+
+> As Query Parameter
+
+```
+?page=1&per_page=50
+```
+
+> As Header
+
+```
+X-Page: 1
+X-Per-Page: 50
+```
+
+By default de API returns 12 items per page. This can be increased to a maximum of 50 items per page.
+
+## Sorting
+
+> Sort ID Descending and Name Ascending
+
+```
+?sort=-id,name
+```
+
+The API supports sorting ascending or descending sorting on multiple columns (seperated by a comma) on the resources.
+
+**Sortable columns are whitelisted inside the API, there is currently no documentation on what columns are whitelisted**
+
+## Searching
+
+> Search for name LIKE "Kevin" and company That Ends With "4News"
+
+```
+?search[name]=Kevin&search[company]=$:4News
+```
+
+Searching can be done on multiple columns, we use the URL array syntax for this.  
+The basic syntax is `operator:value`, so: `=:Maps4News`
+
+**The same is for searchable columns, these are whitelisted per resource**
+
+The available operators are:
+
+ - `!`: Not operator
+ - `=`: Equals operator
+ - `>`: Bigger than operator
+ - `<`: Smaller than operator
+ - `>=`: Bigger than or equals operator
+ - `<=`: Smaller than or equals operator
+ - `^`: Starts with operator
+ - `$`: Ends with operator
+ - Or no operator, that will result in a `LIKE` statement
+
+# Keywords
+
+There are a few keywords throughout the API that you can use in the url as shortcuts to certain resources.
+
+```
+GET /users/me
+```
+
+For example, you can use `me` as an keyword for a user. This will return the resource of the logged in user.
+
+<br/>
+
+```
+GET /organisations/mine
+```
+
+A manager can use the `mine` keyword to get a list of organisations he/she manages.
+
+<br/>
+
+```
+GET /jobs/1/revisions/last
+```
+
+To get the last revision for a job, you can use the `last` keyword.

config/esdoc-wrapper.json

@@ -19,7 +19,7 @@ search: true
 
 Welcome to the API documentation for Maps4News.
 
-This API allows you to manage everything about your account and your organisation. As well as generate Maps.
+Our API allows you to manage everything about your Maps4News account and your organisation. As well as generate Maps.
 
 # API Wrapper
 
@@ -121,10 +121,10 @@ You must have a valid client registered with us to be able to use the API. Clien
 
 # Next
 
-The next step in learning about our API would be to look into our extensive documentation about all the available endpoints.
+The next step in learning about our API would be to look into our OpenAPI documentation about all the available endpoints.
 
-[API Swagger docs](api.html)
+[API OpenAPI (Swagger) Definition](/api/index.html)
 
 Our you can look into how the wrapper works.
 
-[API Wrapper docs](wrapper.html)
+[API Wrapper Class Documentation](/wrapper/index.html)

package.json

@@ -4,4 +4,4 @@
  - [API](/api.html)
    - [API OpenAPI (Swagger) Definition](/api/index.html)
  - [API Wrapper](/wrapper.html)
-   - [API Wrapper API (Class) Documentation](/wrapper/index.html)
+   - [API Wrapper Class Documentation](/wrapper/index.html)