From bc90107e5ba19f64ca0abfb6eab8b2d1df9e014c Mon Sep 17 00:00:00 2001 From: David Ethell Date: Wed, 8 May 2024 06:03:11 -0400 Subject: [PATCH] feat(docs): Update documentation --- docs/faq-generated-code.md | 10 ++++++++++ docs/usage.md | 12 ++++++++++-- 2 files changed, 20 insertions(+), 2 deletions(-) diff --git a/docs/faq-generated-code.md b/docs/faq-generated-code.md index 4ca865c0..6c6bb057 100644 --- a/docs/faq-generated-code.md +++ b/docs/faq-generated-code.md @@ -36,6 +36,16 @@ If you have control over the OpenAPI (i.e. you're not getting it from a third pa No. The fact that you can change the code while the server is running is what makes mocking in Counterfact so pleasant. It watches for file changes and updates automatically. And the state of your context objects is preserved. You can even change the definition of a context object (`_.context.js`) and Counterfact will preserve the values of any properties you didn't explicitly change. +## Can I have more granular control over when the generated code is created? + +Yes. Maybe you're working on a feature and a recent Counterfact bump has caused your types to get updated and it's cluttering your staging area. No problem. You can use the `--generate`, `--generate-types` and `--generate-routes` options to have more control over when the generated code is created. This allows you to generate the types and routes separately and to run the server without generating the code. + +```bash +npx counterfact my-api.yml --generate-types +``` + +You can use the `--watch`, `--watch-types` and `--watch-routes` flags to have Counterfact watch the types and routes files for changes and regenerate the code when they change. Watching will always include generating the code. + ## After reading this FAQ and now I have even more questions! Please reach out by [creating an issue](https://github.com/pmcelhaney/counterfact/issues). diff --git a/docs/usage.md b/docs/usage.md index d5682924..4b0f686a 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -37,7 +37,15 @@ Arguments: Options: --port server port number (default: 3100) --swagger include swagger-ui - --open open a browser + -o, --open open a browser + -g, --generate generate all code for both routes and types + --generate-types generate types + --generate-routes generate routes + -w, --watch generate + watch all code for changes + --watch-types generate + watch types for changes + --watch-routes generate + watch routes for changes + -s, --serve start the mock server + -r, --repl start the REPL --proxy-url proxy URL --prefix base path from which routes will be served (e.g. /api/v1) -h, --help display help for command @@ -70,7 +78,7 @@ After generating code you should have three directories: - 📂 **paths** contains the implementation of each endpoint, a.k.a. routes. Counterfact uses the word "paths" because it corresponds to the `/paths` section of the spec. - 📂 **path-types** contains the type information for paths. -The code under `components` and `path-types` is regenerated every time you run Counterfact, so that the types can stay in sync with any OpenAPI changes. The code under paths is minimal boilerplate that you're meant to edit by hand. Counterfact will not overwrite your changes in the `paths` directory, but it will add new files when necessary. +When you launch Counterfact with no command line options, the code under `components` and `path-types` is regenerated every time you run Counterfact, so that the types can stay in sync with any OpenAPI changes. The code under paths is minimal boilerplate that you're meant to edit by hand. Counterfact will not overwrite your changes in the `paths` directory, but it will add new files when necessary. If you use any of the command line options then it will only regenerate the code when you tell it to via the `--watch` or `--generate` options. See also [Generated Code FAQ](./faq-generated-code.md)