automatically generate postman collections

uses apidoc-postman to generate api collection from api docs

Co-Authored-By: Kyle Rubenok <[email protected]>

Author: meldunn

.github/PULL_REQUEST_TEMPLATE.md

@@ -15,7 +15,7 @@ Please delete options that are not relevant.
 -   [ ] New feature (non-breaking change which adds functionality)
 -   [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
 -   [ ] New release
--   [ ] This change requires a documentation update
+-   [ ] This change requires a documentation update (run `npm run docs` and `npm run docs-postman` after changes)
 
 ### How has this been tested?
 
@@ -24,12 +24,6 @@ Please describe the tests that you ran to verify your changes. Provide instructi
 -   [ ] Test A
 -   [ ] Test B
 
-**Test Configuration**:
-
-**Firmware version:**
-**Hardware:**
-**Toolchain:**
-**SDK:**
 
 ### Questions for code reviewers?
 

docs/api/api_data.js

@@ -1 +1,16 @@
-define({  "name": "hackerAPI",  "version": "0.0.8",  "description": "Documentation for the API used for mchacks",  "defaultVersion": "0.0.8",  "title": "hackerAPI documentation",  "url": "https://api.mchacks.ca/api",  "sampleUrl": "https://api.mchacks.ca/api",  "apidoc": "0.3.0",  "generator": {    "name": "apidoc",    "time": "2020-11-01T22:01:33.009Z",    "url": "http://apidocjs.com",    "version": "0.17.7"  }});
+define({
+  "name": "hackerAPI",
+  "version": "0.0.8",
+  "description": "Documentation for the API used for mchacks",
+  "defaultVersion": "0.0.8",
+  "title": "hackerAPI documentation",
+  "url": "https://api.mchacks.ca/api",
+  "sampleUrl": "https://api.mchacks.ca/api",
+  "apidoc": "0.3.0",
+  "generator": {
+    "name": "apidoc",
+    "time": "2021-06-15T03:37:22.945Z",
+    "url": "http://apidocjs.com",
+    "version": "0.17.7"
+  }
+});

docs/api/api_data.json

@@ -1 +1,16 @@
-{  "name": "hackerAPI",  "version": "0.0.8",  "description": "Documentation for the API used for mchacks",  "defaultVersion": "0.0.8",  "title": "hackerAPI documentation",  "url": "https://api.mchacks.ca/api",  "sampleUrl": "https://api.mchacks.ca/api",  "apidoc": "0.3.0",  "generator": {    "name": "apidoc",    "time": "2020-11-01T22:01:33.009Z",    "url": "http://apidocjs.com",    "version": "0.17.7"  }}
+{
+  "name": "hackerAPI",
+  "version": "0.0.8",
+  "description": "Documentation for the API used for mchacks",
+  "defaultVersion": "0.0.8",
+  "title": "hackerAPI documentation",
+  "url": "https://api.mchacks.ca/api",
+  "sampleUrl": "https://api.mchacks.ca/api",
+  "apidoc": "0.3.0",
+  "generator": {
+    "name": "apidoc",
+    "time": "2021-06-15T03:37:22.945Z",
+    "url": "http://apidocjs.com",
+    "version": "0.17.7"
+  }
+}

docs/api/api_project.js

@@ -0,0 +1 @@
+{"info":{"name":"hackerAPI","description":"Documentation for the API used for mchacks","version":"0.0.8","schema":"https://schema.getpostman.com/json/collection/v2.1.0/"},"item":[{"name":"Account","item":[{"name":"gets information from an account with mongoid ':id'","request":{"auth":null,"method":"GET","url":"{{base_url}}/account/:id","header":[],"body":{"mode":"raw","raw":""}}},{"name":"Get all of the invites.","request":{"auth":null,"method":"GET","url":"{{base_url}}/account/invite","header":[],"body":{"mode":"raw","raw":""}}},{"name":"get information about own account","request":{"auth":null,"method":"GET","url":"{{base_url}}/account/self","header":[],"body":{"mode":"raw","raw":""}}},{"name":"create a new account","request":{"auth":null,"method":"POST","url":"{{base_url}}/account/","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":""}}},{"name":"invites a user to create an account with the specified accountType","request":{"auth":null,"method":"POST","url":"{{base_url}}/account/invite","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":""}}},{"name":"update an account's information","request":{"auth":null,"method":"PATCH","url":"{{base_url}}/account/:id","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":""}}}]},{"name":"Authentication","item":[{"name":"retrieve rolebindings for a user given by their user id :id","request":{"auth":null,"method":"GET","url":"{{base_url}}/auth/rolebindings/:id","header":[],"body":{"mode":"raw","raw":""}}},{"name":"get roles","request":{"auth":null,"method":"GET","url":"{{base_url}}/auth/roles","header":[],"body":{"mode":"raw","raw":""}}},{"name":"logout of service","request":{"auth":{"type":"bearer","basic":[],"bearer":[{"key":"token","value":"{{: public_token}}","type":"string"}]},"method":"GET","url":"{{base_url}}/auth/logout","header":[],"body":{"mode":"raw","raw":""}}},{"name":"resend confirmation token","request":{"auth":null,"method":"GET","url":"{{base_url}}/auth/confirm/resend","header":[],"body":{"mode":"raw","raw":""}}},{"name":"confirm account using the JWT in :token","request":{"auth":null,"method":"POST","url":"{{base_url}}/auth/confirm/:token","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":""}}},{"name":"forgot password route","request":{"auth":{"type":"bearer","basic":[],"bearer":[{"key":"token","value":"{{: public_token}}","type":"string"}]},"method":"POST","url":"{{base_url}}/auth/password/forgot","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":""}}},{"name":"login to the service","request":{"auth":{"type":"bearer","basic":[],"bearer":[{"key":"token","value":"{{: public_token}}","type":"string"}]},"method":"POST","url":"{{base_url}}/auth/login","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":""}}},{"name":"reset password","request":{"auth":{"type":"bearer","basic":[],"bearer":[{"key":"token","value":"{{: must have authentication token_token}}","type":"string"}]},"method":"POST","url":"{{base_url}}/auth/password/reset","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":""}}},{"name":"change password for logged in user","request":{"auth":{"type":"bearer","basic":[],"bearer":[{"key":"token","value":"{{: Must be logged in_token}}","type":"string"}]},"method":"PATCH","url":"{{base_url}}/auth/password/change","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":""}}}]},{"name":"Hacker","item":[{"name":"get a hacker's information","request":{"auth":null,"method":"GET","url":"{{base_url}}/hacker/:id","header":[],"body":{"mode":"raw","raw":""}}},{"name":"get a hacker's information","request":{"auth":null,"method":"GET","url":"{{base_url}}/hacker/email/:email","header":[],"body":{"mode":"raw","raw":""}}},{"name":"get the resume for a hacker.","request":{"auth":{"type":"bearer","basic":[],"bearer":[{"key":"token","value":"{{Must be logged in, and the account id must be linked to the hacker._token}}","type":"string"}]},"method":"GET","url":"{{base_url}}/hacker/resume:id","header":[],"body":{"mode":"raw","raw":""}}},{"name":"Gets the stats of all of the hackers who have applied.","request":{"auth":null,"method":"GET","url":"{{base_url}}/hacker/stats","header":[],"body":{"mode":"raw","raw":""}}},{"name":"get information about logged in sponsor","request":{"auth":{"type":"bearer","basic":[],"bearer":[{"key":"token","value":"{{: Sponsor_token}}","type":"string"}]},"method":"GET","url":"{{base_url}}/sponsor/self","header":[],"body":{"mode":"raw","raw":""}}},{"name":"get information about own hacker","request":{"auth":null,"method":"GET","url":"{{base_url}}/hacker/self","header":[],"body":{"mode":"raw","raw":""}}},{"name":"create a new hacker","request":{"auth":null,"method":"POST","url":"{{base_url}}/hacker/","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":""}}},{"name":"upload or update resume for a hacker.","request":{"auth":{"type":"bearer","basic":[],"bearer":[{"key":"token","value":"{{Must be logged in, and the account id must be linked to the hacker._token}}","type":"string"}]},"method":"POST","url":"{{base_url}}/hacker/resume/:id","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":""}}},{"name":"","request":{"auth":{"type":"bearer","basic":[],"bearer":[{"key":"token","value":"{{Administrator_token}}","type":"string"}]},"method":"POST","url":"{{base_url}}/hacker/email/dayOf/:id","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":""}}},{"name":"","request":{"auth":{"type":"bearer","basic":[],"bearer":[{"key":"token","value":"{{Administrator_token}}","type":"string"}]},"method":"POST","url":"{{base_url}}/hacker/email/weekOf/:id","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":""}}},{"name":"","request":{"auth":{"type":"bearer","basic":[],"bearer":[{"key":"token","value":"{{Administrator_token}}","type":"string"}]},"method":"POST","url":"{{base_url}}/hacker/email/weekOf/:id","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":""}}},{"name":"accept array of Hackers","request":{"auth":{"type":"bearer","basic":[],"bearer":[{"key":"token","value":"{{Administrator_token}}","type":"string"}]},"method":"PATCH","url":"{{base_url}}/hacker/batchAccept/","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":""}}},{"name":"accept a Hacker","request":{"auth":{"type":"bearer","basic":[],"bearer":[{"key":"token","value":"{{Administrator_token}}","type":"string"}]},"method":"PATCH","url":"{{base_url}}/hacker/accept/:id","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":""}}},{"name":"accept a Hacker by email","request":{"auth":{"type":"bearer","basic":[],"bearer":[{"key":"token","value":"{{Administrator_token}}","type":"string"}]},"method":"PATCH","url":"{{base_url}}/hacker/acceptEmail/:email","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":""}}},{"name":"update a hacker's status to be 'Checked-in'. Note that the Hacker must eitehr be Accepted or Confirmed.","request":{"auth":{"type":"bearer","basic":[],"bearer":[{"key":"token","value":"{{Administrator_token}}","type":"string"}]},"method":"PATCH","url":"{{base_url}}/hacker/checkin/:id","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":""}}},{"name":"update a hacker's information.","request":{"auth":null,"method":"PATCH","url":"{{base_url}}/hacker/:id","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":""}}},{"name":"Allows confirmation of hacker attendence if they are accepted. Also allows change from 'confirmed' to 'withdrawn'.","request":{"auth":{"type":"bearer","basic":[],"bearer":[{"key":"token","value":"{{Administrator_token}}","type":"string"}]},"method":"PATCH","url":"{{base_url}}/hacker/confirmation/:id","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":""}}},{"name":"update a hacker's status","request":{"auth":{"type":"bearer","basic":[],"bearer":[{"key":"token","value":"{{Administrator_token}}","type":"string"}]},"method":"PATCH","url":"{{base_url}}/hacker/status/:id","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":""}}}]},{"name":"Index","item":[{"name":"version","request":{"auth":{"type":"bearer","basic":[],"bearer":[{"key":"token","value":"{{public_token}}","type":"string"}]},"method":"GET","url":"{{base_url}}/","header":[],"body":{"mode":"raw","raw":""}}}]},{"name":"Role","item":[{"name":"create a new role","request":{"auth":null,"method":"POST","url":"{{base_url}}/api/role/","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":""}}}]},{"name":"Search","item":[{"name":"provide a specific query for any defined model","request":{"auth":null,"method":"GET","url":"{{base_url}}/search/","header":[],"body":{"mode":"raw","raw":""}}}]},{"name":"Settings","item":[{"name":"Get the settings for the current hackathon","request":{"auth":{"type":"bearer","basic":[],"bearer":[{"key":"token","value":"{{public_token}}","type":"string"}]},"method":"GET","url":"{{base_url}}/settings/","header":[],"body":{"mode":"raw","raw":""}}},{"name":"Patch the settings for the current hackathon","request":{"auth":{"type":"bearer","basic":[],"bearer":[{"key":"token","value":"{{Administrators_token}}","type":"string"}]},"method":"PATCH","url":"{{base_url}}/settings/","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":""}}}]},{"name":"Sponsor","item":[{"name":"get a sponsor's information","request":{"auth":null,"method":"GET","url":"{{base_url}}/sponsor/:id","header":[],"body":{"mode":"raw","raw":""}}},{"name":"create a new sponsor","request":{"auth":null,"method":"POST","url":"{{base_url}}/sponsor/","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":""}}},{"name":"update a sponsor","request":{"auth":null,"method":"PATCH","url":"{{base_url}}/sponsor/","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":""}}}]},{"name":"Team","item":[{"name":"get a team's information","request":{"auth":null,"method":"GET","url":"{{base_url}}/team/:id","header":[],"body":{"mode":"raw","raw":""}}},{"name":"create a new team consisting of only the logged in user","request":{"auth":null,"method":"POST","url":"{{base_url}}/team/","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":""}}},{"name":"Allows a logged in hacker to leave current team","request":{"auth":null,"method":"PATCH","url":"{{base_url}}/team/leave/","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":""}}},{"name":"Allows a logged in hacker to join a team by name","request":{"auth":null,"method":"PATCH","url":"{{base_url}}/team/join/","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":""}}},{"name":"Update a team's information. The team is specified by the hacker belonging to it.","request":{"auth":null,"method":"PATCH","url":"{{base_url}}/team/:hackerId","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":""}}}]},{"name":"Travel","item":[{"name":"get a traveler's information","request":{"auth":null,"method":"GET","url":"{{base_url}}/travel/:id","header":[],"body":{"mode":"raw","raw":""}}},{"name":"get a travel's information","request":{"auth":null,"method":"GET","url":"{{base_url}}/travel/email/:email","header":[],"body":{"mode":"raw","raw":""}}},{"name":"get information about own hacker's travel","request":{"auth":null,"method":"GET","url":"{{base_url}}/travel/self","header":[],"body":{"mode":"raw","raw":""}}},{"name":"create a new travel","request":{"auth":null,"method":"POST","url":"{{base_url}}/travel/","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":""}}},{"name":"update a traveler's offer","request":{"auth":{"type":"bearer","basic":[],"bearer":[{"key":"token","value":"{{Administrator_token}}","type":"string"}]},"method":"PATCH","url":"{{base_url}}/travel/offer/:id","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":""}}},{"name":"update a traveler's status","request":{"auth":{"type":"bearer","basic":[],"bearer":[{"key":"token","value":"{{Administrator_token}}","type":"string"}]},"method":"PATCH","url":"{{base_url}}/travel/status/:id","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":""}}}]},{"name":"Volunteer","item":[{"name":"get a volunteer's information","request":{"auth":null,"method":"GET","url":"{{base_url}}/volunteer/:id","header":[],"body":{"mode":"raw","raw":""}}},{"name":"create a new volunteer","request":{"auth":null,"method":"POST","url":"{{base_url}}/volunteer/","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":""}}}]}]}

docs/api/api_project.json

@@ -14,14 +14,11 @@
     2. `mongodb`: <https://docs.mongodb.com/manual/installation/>
         1. Make sure you also have the `/data/db` directory.
         2. To test the installation, run `mongod`.
-    3. `node`: <https://nodejs.org/en/download/>
+    3. `node`: <https://nodejs.org/en/download/> (Validated Node version is specified in [`.nvmrc`](../../hackerAPI/.nvmrc) )
     4. `npm`: <https://www.npmjs.com/get-npm>.
     5. `Postman`: <https://www.getpostman.com/downloads/>. We use this for testing the API locally.
-3. Make sure you have the following (only if you are going to be publishing this as a kubernetes cluster on google cloud):
-    1. `kubectl`: <https://kubernetes.io/docs/tasks/tools/install-kubectl/>
-    2. `gcloud`: <https://cloud.google.com/sdk/install>
-4. Create a `.env` file in the root directory, and populate the fields as per `.env.example`.
-5. run `npm install`
+3. Create a `.env` file in the root directory, and populate the fields as per `.env.example`.
+4. run `npm install`
 
 ## Setting up the database
 
@@ -31,4 +28,17 @@
 
 ## Testing the API
 
-In order to test that you have set up the API properly, run `npm run test`.
+### Automated Testing
+
+In order to test that you have set up the API properly, run `npm run test`.
+
+### Testing with Postman
+
+1. Import Postman Collection from [`postman.json`](./api/postman.json)
+2. [Create a new Environment](https://learning.postman.com/docs/sending-requests/managing-environments/) in Postman with **Variables** for `base_url`. Typical values for these might look like this. You may or may not have the same credentials in your Dev Environment as the Production Database.
+
+    |                | Local Dev Environment | Production Environment |
+    |----------------|-----------------------|------------------------|
+    | base_url       | http://localhost:3000 | https://api.mchacks.ca |
+
+API parameters are not currently automatically imported by the Postman generation script. A change to a different API Doc generation tool in future could make this a more supported use case by Postman.