add more usage examples

Author: David Blackman

README.md

@@ -23,6 +23,29 @@ Note that this is an interactive evaluation form for figuring out which queries
 
 ## tl;dr
 
+### Try it out yourself!
+
+This is a contrived example because our old and new servers are the same, but they return random data, so it is a good way to quickly see diffs.
+
+
+From CSV input:
+```
+api-diff \
+  --old.host http://names.drycodes.com/ \
+  --new.host http://names.drycodes.com/ \
+  --endpoint "/10" \
+  --input_csv docs/examples/input-names-drycodes.csv
+```
+
+From a file of http paths
+
+```
+api-diff \
+  --old.host http://names.drycodes.com/ \
+  --new.host http://names.drycodes.com/ \
+  --input_queries docs/examples/input-names-drycodes.txt
+```
+
 ### Compare two servers
 
 ```
@@ -141,6 +164,9 @@ An example config looks like this
   # only required if using authStyle="param"
   # authParam: "api_key",
 
+  # optional, if using authStyle="header"
+  # authType: "Basic",
+
   # first keyType listed here will be the default if a
   # keyType is not specified in the commandline options to # compare
   keyTypes: ['test', 'live'],
@@ -181,6 +207,8 @@ APICOM_STAGING_TEST_KEY=XXXX
 APICOM_STAGING_LIVE_KEY=XXXX
 ```
 
+If your server requires authorization in request params, set authStyle="param" and authParam to the request parameter name the server expects. If your server uses the HTTP Authoization header, then set authStyle="header" and (optionally) authType to what auth type prefix the server expects, such as "Basic" or "Bearer" - this can be omitted if your server takes bare keys in the Authoization header.
+
 Our config defines two types of keys - test and live. It also defines two key environments. One for "prod" and one for "staging," the host configs for "local" and "user" are both configured to look in the "staging" key env"
 
 ### Specifying a server

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blackmad/api-diff",
-  "version": "1.0.31",
+  "version": "1.0.32",
   "description": "",
   "main": "index.js",
   "scripts": {

src/api-diff/formatters/console-formatter.ts

@@ -6,7 +6,10 @@ import * as _ from 'lodash';
 
 import * as config from '../../config';
 import { Change } from '../change';
-import { CompareFormatter, FinishedStats, makeResponseTimesHistogram } from './compare-formatter';
+import {
+  CompareFormatter,
+  FinishedStats,
+} from './compare-formatter';
 import { ApiEnv } from '../../apiEnv';
 
 export default class ConsoleFormatter extends CompareFormatter {
@@ -15,7 +18,9 @@ export default class ConsoleFormatter extends CompareFormatter {
       const commandParts: string[] = [];
 
       if (config.CONFIG_FILE_ENV_VARIABLE && config.API_DIFF_CONFIG_FILE) {
-        commandParts.push(`${config.CONFIG_FILE_ENV_VARIABLE}=${config.API_DIFF_CONFIG_FILE}`);
+        commandParts.push(
+          `${config.CONFIG_FILE_ENV_VARIABLE}=${config.API_DIFF_CONFIG_FILE}`,
+        );
       }
 
       if (_.some(process.argv, (arg) => arg.includes('ts-node'))) {
@@ -32,8 +37,12 @@ export default class ConsoleFormatter extends CompareFormatter {
       return commandParts.join(' ');
     };
     const outputLines = `${JSON.stringify(change.query.params)}
-    ${apiEnvToApiSh(this.oldApiEnv)} ${change.oldResponse.request?.res?.responseUrl}
-    ${apiEnvToApiSh(this.newApiEnv)} ${change.newResponse.request.res.responseUrl}`;
+    ${apiEnvToApiSh(this.oldApiEnv)} ${
+      change.oldResponse.request?.res?.responseUrl
+}
+    ${apiEnvToApiSh(this.newApiEnv)} ${
+  change.newResponse.request.res.responseUrl
+}`;
 
     if (!change.delta) {
       this.writeln(chalk.cyan(`Unchanged: ${outputLines}`));
@@ -46,38 +55,47 @@ export default class ConsoleFormatter extends CompareFormatter {
   }
 
   onFinished(finishedStats: FinishedStats): Promise<void> {
-    this.writeln(`Elapsed: ${(Date.now() - this.startDate.getTime()) / 1000} seconds`);
+    this.writeln(
+      `Elapsed: ${(Date.now() - this.startDate.getTime()) / 1000} seconds`,
+    );
 
-    this.writeln('');
+    // this.writeln('');
 
-    // Response times table
-    this.writeln('Response times');
-    const oldResponseTimes = makeResponseTimesHistogram(finishedStats.old.responseTimes);
-    const newResponseTimes = makeResponseTimesHistogram(finishedStats.new.responseTimes);
+    // // Response times table
+    // this.writeln('Response times');
+    // const oldResponseTimes = makeResponseTimesHistogram(finishedStats.old.responseTimes);
+    // const newResponseTimes = makeResponseTimesHistogram(finishedStats.new.responseTimes);
 
-    const responseTimesTable = [['', 'old', 'new']];
-    _.keys(oldResponseTimes).forEach((key) => {
-      responseTimesTable.push([
-        key,
-        oldResponseTimes[key].toString(),
-        newResponseTimes[key].toString(),
-      ]);
-    });
+    // const responseTimesTable = [['', 'old', 'new']];
+    // _.keys(oldResponseTimes).forEach((key) => {
+    //   responseTimesTable.push([
+    //     key,
+    //     oldResponseTimes[key].toString(),
+    //     newResponseTimes[key].toString(),
+    //   ]);
+    // });
 
-    this.writeln(table(responseTimesTable));
+    // this.writeln(table(responseTimesTable));
 
     // Status codes table
-    this.writeln('Status codes');
-    const statusCodesTable = [['', 'old', 'new']];
-    _.keys(finishedStats.old.statusCodes).forEach((key) => {
-      statusCodesTable.push([
-        key,
-        finishedStats.old.statusCodes[key].toString(),
-        finishedStats.old.statusCodes[key].toString(),
-      ]);
-    });
-
-    this.writeln(table(statusCodesTable));
+    // Only output this if there's a reason to, that we had some non-200 codes
+    if (
+      !_.isEqual(_.keys(finishedStats.new.statusCodes), ['200'])
+      || !_.isEqual(_.keys(finishedStats.old.statusCodes), ['200'])
+    ) {
+      this.writeln('Status codes');
+
+      const statusCodesTable = [['', 'old', 'new']];
+      _.keys(finishedStats.old.statusCodes).forEach((key) => {
+        statusCodesTable.push([
+          key,
+          finishedStats.old.statusCodes[key].toString(),
+          finishedStats.new.statusCodes[key].toString(),
+        ]);
+      });
+
+      this.writeln(table(statusCodesTable));
+    }
 
     return Promise.resolve();
   }

src/api-diff/query-reader.ts

@@ -4,7 +4,6 @@
 import * as queryString from 'querystring';
 import * as fs from 'fs';
 import * as _ from 'lodash';
-import chalk from 'chalk';
 import parseCsvSync from 'csv-parse/lib/sync';
 import { failedExit } from '../cli-utils';
 import { ParsedArgs } from './argv';
@@ -30,15 +29,6 @@ type QueryReaderArgs = Pick<
  * @returns {Query[]} list of queries read
  */
 function readQueriesHelper(argv: QueryReaderArgs): Query[] {
-  const hasInputFile = argv.input_params || argv.input_csv;
-  if ((argv.endpoint && !hasInputFile) || (!argv.endpoint && hasInputFile)) {
-    console.error(
-      chalk.red(
-        'Must specify both --endpoint and (--input_params or --input_csv) , perhaps you wanted --input_queries?',
-      ),
-    );
-  }
-
   /**
    * Convert a /path?params=X string to a Query
    *