Quickstart command out of date

[treyturner]

Quickstart suggests the following command:

npx counterfact@latest https://petstore3.swagger.io/api/v3/openapi.json api --open

This doesn't seem to match the syntax provided by --help which indicates options should go between the command and the schema location:

Usage: counterfact [options] [openapi.yaml] [destination]

I thought this might be why the server wasn't starting, but moving the option flag alone didn't fix it. The server still wasn't started, I'm returned immediately to my shell, and the opened browser naturally can't connect. Using debug output, I determined generate is set to { routes: undefined, types: undefined } when --open is used. Adding -g as an option alongside --open does result in the expected route and type generation, but the server still stops immediately after being started and I'm returned to a shell. I had to additionally add -s as an option to keep the server running and for the browser opened by --open to correctly load the Swagger UI.

So to summarize,

Reproduction

1. Run the quickstart command, ie. npx counterfact --open https://api.artifactsmmo.com/openapi.json

Expected result:

1. Routes and types are generated
2. Server is started and remains running, thereby serving the Swagger UI when the browser is opened

Actual result:

1. Routes and types aren't generated
2. Server is started (according to debug) but immediately stops

Possible fixes

• Change generate and serve defaults when --open is specified to be more intuitive
• Update quickstart command to fix option argument position and include -g and -s

Debug output using --open:

tturner@dev:~/wsldev/counterfact-test$ DEBUG=counterfact:* npx counterfact --open https://api.artifactsmmo.com/openapi.json
  counterfact:server:repository dirname is /home/tturner/wsldev/counterfact-test/node_modules/counterfact/dist/typescript-generator +0ms
  counterfact:bin:counterfact running ./bin/counterfact.js +0ms
  counterfact:bin:counterfact executing the main function +3ms
  counterfact:bin:counterfact options: { port: 3100, prefix: '', open: true } +0ms
  counterfact:bin:counterfact source: https://api.artifactsmmo.com/openapi.json +1ms
  counterfact:bin:counterfact destination: . +0ms
  counterfact:bin:counterfact loading counterfact ({ basePath: '/home/tturner/wsldev/counterfact-test', generate: { routes: undefined, types: undefined }, includeSwaggerUi: true, openApiPath: 'https://api.artifactsmmo.com/openapi.json', port: 3100, proxyPaths: Map(1) { '' => false }, proxyUrl: '', routePrefix: '', startRepl: undefined, startServer: undefined, watch: { routes: undefined, types: undefined } }) +0ms
  counterfact:server:create-koa-app basePath: /home/tturner/wsldev/counterfact-test +0ms
  counterfact:server:create-koa-app routes [] +0ms
  counterfact:bin:counterfact loaded counterfact {
  basePath: '/home/tturner/wsldev/counterfact-test',
  generate: { routes: undefined, types: undefined },
  includeSwaggerUi: true,
  openApiPath: 'https://api.artifactsmmo.com/openapi.json',
  port: 3100,
  proxyPaths: Map(1) { '' => false },
  proxyUrl: '',
  routePrefix: '',
  startRepl: undefined,
  startServer: undefined,
  watch: { routes: undefined, types: undefined }
} +332ms
____ ____ _  _ _ _ ___ ____ ____ ____ ____ ____ ___
|___ [__] |__| |\|  |  |=== |--< |--- |--| |___  |
             maybe she’s born with it…

| API Base URL  ==> http://localhost:3100
| Swagger UI    ==> http://localhost:3100/counterfact/swagger/

| Instructions  ==> https://counterfact.dev/docs/usage.html
| Help/feedback ==> https://github.com/pmcelhaney/counterfact/issues


  counterfact:bin:counterfact starting server +1ms
  counterfact:bin:counterfact started server +0ms
  counterfact:bin:counterfact opening browser +0ms
  counterfact:bin:counterfact opened browser +5ms
tturner@dev:~/wsldev/counterfact-test$

Debug output without --open:

Here's the (start) of the debug output when started without --open, where we can see it actually starting to get busy.

tturner@dev:~/wsldev/counterfact-test$ DEBUG=counterfact:* npx counterfact https://api.artifactsmmo.com
/openapi.json
  counterfact:server:repository dirname is /home/tturner/wsldev/counterfact-test/node_modules/counterfact/dist/typescript-generator +0ms
  counterfact:bin:counterfact running ./bin/counterfact.js +0ms
  counterfact:bin:counterfact executing the main function +2ms
  counterfact:bin:counterfact options: { port: 3100, prefix: '', repl: true, serve: true, watch: true, generate: true } +0ms
  counterfact:bin:counterfact source: https://api.artifactsmmo.com/openapi.json +1ms
  counterfact:bin:counterfact destination: . +0ms
  counterfact:bin:counterfact loading counterfact ({ basePath: '/home/tturner/wsldev/counterfact-test', generate: { routes: true, types: true }, includeSwaggerUi: true, openApiPath: 'https://api.artifactsmmo.com/openapi.json', port: 3100, proxyPaths: Map(1) { '' => false }, proxyUrl: '', routePrefix: '', startRepl: true, startServer: true, watch: { routes: true, types: true } }) +0ms
  counterfact:server:create-koa-app basePath: /home/tturner/wsldev/counterfact-test +0ms
  counterfact:server:create-koa-app routes [] +0ms
  counterfact:bin:counterfact loaded counterfact {
  basePath: '/home/tturner/wsldev/counterfact-test',
  generate: { routes: true, types: true },
  includeSwaggerUi: true,
  openApiPath: 'https://api.artifactsmmo.com/openapi.json',
  port: 3100,
  proxyPaths: Map(1) { '' => false },
  proxyUrl: '',
  routePrefix: '',
  startRepl: true,
  startServer: true,
  watch: { routes: true, types: true }
} +225ms
____ ____ _  _ _ _ ___ ____ ____ ____ ____ ____ ___
|___ [__] |__| |\|  |  |=== |--< |--- |--| |___  |
      my other server’s a Kubernetes cluster

| API Base URL  ==> http://localhost:3100
| Swagger UI    ==> http://localhost:3100/counterfact/swagger/

| Instructions  ==> https://counterfact.dev/docs/usage.html
| Help/feedback ==> https://github.com/pmcelhaney/counterfact/issues

Watching for changes
Starting server
Starting REPL, type .help for more info

  counterfact:bin:counterfact starting server +1ms
  counterfact:typescript-generator:generate generating code from https://api.artifactsmmo.com/openapi.json to /home/tturner/wsldev/counterfact-test +0ms
  counterfact:typescript-generator:generate initializing the .cache directory +0ms
  counterfact:typescript-generator:generate ensuring the directory containing .gitgnore exists +0ms
  counterfact:typescript-generator:generate creating the .gitignore file if it doesn't already exist +0ms
  counterfact:typescript-generator:generate creating the .cache/README.md file +0ms
  counterfact:typescript-generator:generate done initializing the .cache directory +13ms
  counterfact:typescript-generator:generate creating specification from https://api.artifactsmmo.com/openapi.json +0ms
  counterfact:typescript-generator:generate created specification: $o Specification {
  cache: Map(0) {},
  rootUrl: 'https://api.artifactsmmo.com/openapi.json'
} +0ms
  counterfact:typescript-generator:generate reading the #/paths from the specification +0ms
  counterfact:typescript-generator:specification getting requirement at #/paths from  +0ms
  ... etc etc

End of debug output using -g --open

Here we see the server starting and immediately ending I guess

counterfact:server:repository did write /home/tturner/wsldev/counterfact-test/types/paths/resources.types.ts +1ms
counterfact:typescript-generator:generate finished writing the files +502ms
counterfact:bin:counterfact started server +720ms
counterfact:bin:counterfact opening browser +0ms
counterfact:bin:counterfact opened browser +5ms
tturner@dev:~/wsldev/counterfact-test$

[cincauhangus]

I guess the correct quick start command is now:

npx counterfact@latest openapi.yaml api --generate --serve --swagger --open

I prefer generating the files in a separate folder to avoid clashes

npx counterfact@latest openapi.yaml .counterfact-mock-server --generate --serve --swagger --open

[treyturner]

I guess the correct quick start command is now:

npx counterfact@latest openapi.yaml api --generate --serve --swagger --open

FWIW, the Swagger UI seems to be generated in any case, without --swagger, whether --open is supplied or not. Not sure --swagger's purpose.

[pmcelhaney]

Thanks, it should actually be:

npx counterfact@latest https://petstore3.swagger.io/api/v3/openapi.json api 

When no options are supplied, Counterfact defaults to doing everything (generates code, watches for changes, starts the server, and starts the REPL).

The --swagger option is pointless, as there's no real advantage to starting the server without Swagger UI.

This is great feedback, thank you! I've fixed the immediate problem (getting rid of --open in the quick start docs). Leaving this issue open until I clean up the remaining confusion.