Merge branch 'dev' into en-621

README.md

@@ -122,7 +122,13 @@ Download MongoDB Compass (MongoDB GUI)
 
 - https://www.mongodb.com/download-center/compass
 
-Create a `cve_dev` and `cve_test` database in Compass. The collections will be automatically created when the API starts storing documents.
+Create a `cve_dev` database in Compass. The collections will be automatically created when the API starts storing documents.
+
+You can populate the database with test data using:
+
+```sh
+npm run populate:dev
+```
 
 3. Start the node application
 
@@ -135,19 +141,26 @@ npm run start:dev
 
 ### Api Documentation
 
-We have established an [openapi.yml](https://github.com/CVEProject/cve-services/blob/dev/docs/openapi.yml) file that follows the Open API v3.0.2 specification. We are working to keep this up to date with our dev branch as we work towards our first release. We hope to use this to generate some live documentation soon along with an official project page.
+API documentation is generated using [swagger-autogen](https://github.com/davibaltar/swagger-autogen) which ensures that we keep the API specification up to date with any major changes to API routes. Extra information for each API route is defined as a comment in the `index.js` files under the respective controller and all request and response schemas are stored under the `schemas` folder served up by `schemas.controller`.
 
-<!--
-ApiDoc: http://apidocjs.com/
+To ensure you are using the correct API specification the following endpoints can be used:
+- [Staging](https://cveawg-test.mitre.org/api-docs/openapi.json)
+- [Production](https://cveawg.mitre.org/api-docs/openapi.json)
 
-In order to create API docs run:
+Note: The specification file stored in GitHub will only be correct for that branch there could be differences between branches and production.
 
-```sh
-    npm run docs
-```
+If you are developer and want to test changes to the API specification you can generate a specification in one of two ways:
+
+1. Ideal
+
+When you start your local development server using `npm run start:dev` the specification file will be generated. Subsequent changes you will need to reload the server.
+
+If you are updating files in the `schemas` folder you will need to reload the server to see the changes due to the limitations of the require method.
+
+2. Manual
+
+You can use `npm run swagger-autogen` which will generate a new specification file. However, if you run `npm run start:dev` this will generate a specification file so you may need to adjust something if you need to test a specific thing. 
 
-This creates an html file that can be found under apidocs/
--->
 
 ### Unit Testing