Add Optic for documentation

.optic/.gitignore

@@ -0,0 +1,3 @@
+
+captures/
+optic-temp-*

.optic/api/specification.json

@@ -0,0 +1 @@
+[]

.optic/ignore

@@ -0,0 +1,16 @@
+# Default Ignore Rules
+# Learn to configure your own at http://localhost:4000/docs/using/advanced-configuration#ignoring-api-paths
+OPTIONS (.*)
+HEAD (.*)
+GET (.*).htm
+GET (.*).html
+GET (.*).ico
+GET (.*).css
+GET (.*).js
+GET (.*).woff
+GET (.*).woff2
+GET (.*).png
+GET (.*).jpg
+GET (.*).jpeg
+GET (.*).svg
+GET (.*).gif

README.md

@@ -85,6 +85,10 @@ Note that we are overriding the environment variable set in `.env` file because
 
 Note: The difference between exec and run is that, exec executes the command within the running container and run will spin up a new container to run that command. So if you want to run only the tests without docker-compose up, you may do so by running `docker-compose run -e MONGODB_URL=mongodb://mongo:27017/noobjs_test node npm test`
 
+## API Documentation
+
+To simplify documenting your API, we have included [Optic](https://useoptic.com). To use it, you will need to [install the CLI tool](https://useoptic.com/document/#add-an-optic-specification-to-your-api-project), and then you can use `api exec "npm start"` to start capturing your endpoints as you create them. Once you want to review and add them to your API specification run: `api status -- review`.
+
 ## License
 
 MIT

config/express.js

@@ -10,6 +10,7 @@ const compression = require('compression');
 const morgan = require('morgan');
 const cookieParser = require('cookie-parser');
 const bodyParser = require('body-parser');
+const { OpticMiddleware } = require('@useoptic/express-middleware');
 const methodOverride = require('method-override');
 const csrf = require('csurf');
 const cors = require('cors');
@@ -107,6 +108,9 @@ module.exports = function(app, passport) {
     })
   );
 
+  // auto document API endpoints
+  app.use(OpticMiddleware({ enabled: !!(env !== 'production') }));
+
   // use passport session
   app.use(passport.initialize());
   app.use(passport.session());

optic.yml

@@ -0,0 +1,13 @@
+name: "nodejs-express-mongoose-demo"
+# Start your api with Optic by running 'api run <taskname>'
+tasks:
+  start:
+    command: "npm start"
+    inboundUrl: http://localhost:4000
+
+# Capture traffic from a deployed api by running 'api intercept <environment-name>'
+# pass '--chrome' to capture from your browser's network tab
+environments:
+  production:
+    host: https://api.github.com # the hostname of the API we should record traffic from
+    webUI: https://api.github.com/repos/opticdev/optic # the url that should open when a browser flag is passed