Update docs

Author: drwpow

CONTRIBUTING.md

@@ -1,98 +1,100 @@
 # Contributing
 
-Thanks for being willing to contribute!
+Thanks for being willing to contribute! 🙏
 
-**Working on your first Pull Request?** You can learn how from this _free_ series [How to Contribute to an Open Source
-Project on GitHub][egghead]
+**Working on your first Pull Request (PR)?** You can learn how from this _free_ series [How to Contribute to an Open Source Project on GitHub](https://egghead.io/series/how-to-contribute-to-an-open-source-project-on-github)
 
-## Project setup
+## Open issues
+
+Please check out the [the open issues](https://github.com/drwpow/openapi-typescript/issues). Issues labelled [**Help Wanted**](https://github.com/drwpow/openapi-typescript/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) and [**Good First Issue**](https://github.com/drwpow/openapi-typescript/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) are especially good to help with.
+
+Contributing doesn’t have to be in code! Simply answering questions in open issues, or providing workarounds, is just as important a contribution as making pull requests.
+
+## Setup
+
+### Dependencies
 
 1. Install [pnpm](https://pnpm.io/)
 2. Fork and clone the repo
 3. Run `pnpm i` to install dependencies
 4. Create a branch for your PR with `git checkout -b pr/your-branch-name`
 
-It’s also recommended you have [ESLint][eslint] installed and set up correctly. You may also run the command
-`npm run lint` to see lint errors.
+### VS Code setup
 
-> Tip: Keep your `main` branch pointing at the original repository and make pull requests from branches on your fork. To
-> do this, run:
->
-> ```
-> git remote add upstream https://github.com/drwpow/openapi-typescript.git
-> git fetch upstream
-> git branch --set-upstream-to=upstream/main main
-> ```
->
-> This will add the original repository as a "remote" called "upstream," Then fetch the git information from that
-> remote, then set your local `main` branch to use the upstream main branch whenever you run `git pull`. Then you can
-> make all of your pull request branches based on this `main` branch. Whenever you want to update your version of
-> `main`, do a regular `git pull`.
+If using VS Code, the following extensions are recommended (or their equivalent extensions if using another editor)
 
-## Committing and pushing changes
+- [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint)
 
-Please make sure to run the tests (`npm test`) before you commit your changes.
+## Workflow
 
-### Local schemas
+When working locally, run:
 
-This repo supports OpenAPI 2.0 and 3.0. There are some real-world examples located in `tests/v2/specs/*.yaml` and
-`tests/v3/specs/*.yaml`, respectively. Testing large, real schemas was a major goal of this project. Many libraries only
-test the “Petstore” example from Swagger, which is contrived and is missing much complexity from companies’ production
-schemas.
+```bash
+npm run dev
+```
 
-_Note: don’t update the `yaml` schemas with your own custom additions (but if the official versions have updated, then
-it’s fine to update them here). If you’d like to add your schema for testing, then please add them as a new schema, and
-add them to `./expected/*.ts`._
+This will compile the code as you change automatically.
 
-#### Regenerating schemas
+### TDD
 
-If you’ve added a feature or fixed a bug and need to update the generated schemas, run the following:
+This library is a great usecase for [test-driven development (TDD)](https://en.wikipedia.org/wiki/Test-driven_development). If you’re new to this, the basic workflow is:
 
-```
-# 1. re-build the package
-npm run build
-# 2. run the local CLI (not the npm one!)
-./bin/cli.js tests/v3/specs/github.yaml -o tests/v3/expected/github.ts
-# NOTE: on Windows, try running the script on WSL if getting errors
-```
+1. First, write a [test](#testing) that fully outlines what you’d _like_ the output to be.
+2. Make sure this test **fails** when you run `npm test` (yes, _fails!_)
+3. Then, make changes to `src/` until the tests pass.
+
+_Code generation is hard!_ And for that reason, starting with a very clear expectation of your end-goal can make working easier.
+
+### Unit tests or snapshot tests?
+
+This library has both unit tests (tests that test a tiny part of a schema) and snapshot tests (tests that run over an entire, complete schema). When opening a PR, the former are more valuable than the latter, and are always required. However, updating snapshot tests can help with the following:
+
+- Fixing bugs that deal with multiple schemas with remote `$ref`s
+- Fixing Node.js or OS-related bugs
+- Adding a CLI option that changes the entire output
+
+For most PRs, **snapshot tests can be avoided.** But for scenarios similar to the ones mentioned, they can ensure everything is working as expected.
 
-This should update the expected TypeScript definiton.
+### Opening a PR
 
-_Also if this appears in `examples/` feel free to update that, too!_
+When opening a pull request, make sure all of the following is done:
+
+- [x] Tests are added
+- [x] Build passes (`npm run build`)
+- [x] Tests pass (`npm test`)
+- [x] Linting passes (`npm run lint`)
 
 ## Testing
 
-Tests use [Vitest](https://vitest.dev), a modern test-runner based on Jest. To run the tests locally, run:
+This library uses [Vitest](https://vitest.dev/) for testing. There’s a great [VS Code extension](https://marketplace.visualstudio.com/items?itemName=ZixuanChen.vitest-explorer) you can optionally use if you’d like in-editor debugging tools.
 
-```
+### Running tests
+
+💡 The tests test **the production build** in `dist/`. Be sure to run `npm run build` before running tests (or keep `npm run dev` running in the background, which compiles as-you-work)!
+
+To run the entire test suite once, run:
+
+
+```bash
 npm test
 ```
 
 To run an individual test:
 
-```
-npx vitest [part of filename]
+```bash
+npx vitest [partial filename]
 ```
 
-Or to start all tests in watch mode:
+To start the entire test suite in watch mode:
 
-```
+```bash
 npx vitest
 ```
 
-[See docs](https://vitest.dev)
-
-## Help needed
+### Running linting
 
-Please check out the [the open issues][issues]. Issues labelled [**Help Wanted**][help-wanted] and [**Good First
-Issue**][good-first-issue] are especially good to help with.
+To run ESLint on the project:
 
-Also, please watch the repo and respond to questions/bug reports/feature requests! Thanks!
-
-[all-contributors]: https://github.com/all-contributors/all-contributors
-[egghead]: https://egghead.io/series/how-to-contribute-to-an-open-source-project-on-github
-[eslint]: https://eslint.org/
-[good-first-issue]:
-  https://github.com/drwpow/openapi-typescript/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22
-[help-wanted]: https://github.com/drwpow/openapi-typescript/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22
-[issues]: https://github.com/drwpow/openapi-typescript/issues
+```bash
+npm run lint
+```

README.md

@@ -8,22 +8,18 @@
 
 # 📘️ openapi-typescript
 
-🚀 Convert [OpenAPI 3.0][openapi3] and [2.0 (Swagger)][openapi2] schemas to TypeScript interfaces using Node.js.
+🚀 Convert [OpenAPI](https://spec.openapis.org/oas/latest.html) schemas to TypeScript interfaces painlessly using pure Node.js. No Java, node-gyp, or running OpenAPI servers necessary. Uses [Prettier](https://npmjs.com/prettier) to format the output.
 
 **Features**
 
-- ✅ [OpenAPI 3.0][openapi3]
-- ✅ [Swagger 2.0][openapi2]
-- ✅ Supports YAML and JSON schema formats
+- ✅ Supports YAML and JSON
 - ✅ Supports loading via remote URL (simple authentication supported with the `--auth` flag)
 - ✅ Supports remote references: `$ref: "external.yaml#components/schemas/User"`
-- ✅ Formats using [Prettier][prettier]
-- ✅ TypeScript 4.0 features
+- ✅ Prettier formatting is fully customizable to match your existing code style.
 
 **Examples**
 
-- [Stripe, OpenAPI 2.0](./examples/stripe-openapi2.ts)
-- [Stripe, OpenAPI 3.0](./examples/stripe-openapi3.ts)
+[See examples](./examples/)
 
 ## Usage
 
@@ -54,14 +50,12 @@ _Thanks to [@sharmarajdaksh](https://github.com/sharmarajdaksh) for the glob fea
 #### ☁️ Reading specs from remote resource
 
 ```bash
-npx openapi-typescript https://petstore.swagger.io/v2/swagger.json --output petstore.ts
+npx openapi-typescript https://petstore3.swagger.io/api/v3/openapi.yaml --output petstore.d.ts
 
-# 🔭 Loading spec from https://petstore.swagger.io/v2/swagger.json…
-# 🚀 https://petstore.swagger.io/v2/swagger.json -> petstore.ts [650ms]
+# 🔭 Loading spec from https://petstore3.swagger.io/api/v3/openapi.yaml…
+# 🚀 https://petstore3.swagger.io/api/v3/openapi.yaml -> petstore.d.ts [650ms]
 ```
 
-_Note: globbing doesn’t work for remote schemas because there is no reliable way to determine a list of files to select from a remote file system._
-
 _Thanks to [@psmyrdek](https://github.com/psmyrdek) for the remote spec feature!_
 
 #### Using in TypeScript
@@ -76,16 +70,16 @@ type APIResponse = components["schemas"]["APIResponse"];
 
 Because OpenAPI schemas may have invalid TypeScript characters as names, the square brackets are a safe way to access every property.
 
-Also note that there’s a special `operations` interface that you can import `OperationObjects` by their [operationId][openapi-operationid]:
+##### Operations
+
+Operations can be imported directly by their [operationId](https://spec.openapis.org/oas/latest.html#operation-object):
 
 ```ts
 import { operations } from "./generated-schema.ts";
 
 type getUsersById = operations["getUsersById"];
 ```
 
-Even though `operations` isn’t present in your original schema, it’s a simple convenience and won’t disrupt any of your other types.
-
 _Thanks to [@gr2m](https://github.com/gr2m) for the operations feature!_
 
 #### openapi-typescript-fetch
@@ -94,7 +88,6 @@ The generated spec can also be used with [openapi-typescript-fetch](https://www.
 
 ```ts
 import { paths } from "./petstore";
-
 import { Fetcher } from "openapi-typescript-fetch";
 
 // declare fetcher for paths
@@ -163,7 +156,6 @@ npx openapi-typescript schema.yaml
 | `--make-paths-enum`            | `-pe` | `false`  | (optional) Generate an enum of endpoint paths                                                                                           |
 | `--path-params-as-types`       |       | `false`  | (optional) Substitute path parameter names with their respective types                                                                  |
 | `--raw-schema`                 |       | `false`  | Generate TS types from partial schema (e.g. having `components.schema` at the top level)                                                |
-| `--version`                    |       |          | Force OpenAPI version with `--version 3` or `--version 2` (required for `--raw-schema` when version is unknown)                         |
 
 ### 🐢 Node
 
@@ -172,7 +164,7 @@ npm i --save-dev openapi-typescript
 ```
 
 ```js
-import fs from "fs";
+import fs from "node:fs";
 import openapiTS from "openapi-typescript";
 
 // example 1: load [object] as schema (JSON only)
@@ -187,9 +179,7 @@ const output = await openapiTS(localPath);
 const output = await openapiTS("https://myurl.com/v1/openapi.yaml");
 ```
 
-The Node API may be useful if dealing with dynamically-created schemas, or you’re using within context of a larger application. Pass in either a JSON-friendly object to load a schema from memory, or a string to load a schema from a local file or remote URL (it will load the file quickly using built-in Node methods). Note that a YAML string isn’t supported in the Node.js API; either use the CLI or convert to JSON using [js-yaml][js-yaml] first.
-
-⚠️ As of `v4.0`, `openapiTS()` is an async function.
+The Node API may be useful if dealing with dynamically-created schemas, or you’re using within context of a larger application. Pass in either a JSON-friendly object to load a schema from memory, or a string to load a schema from a local file or remote URL (it will load the file quickly using built-in Node methods). Note that a YAML string isn’t supported in the Node.js API; either use the CLI or convert to JSON using [js-yaml](https://www.npmjs.com/package/js-yaml) first.
 
 #### Custom Formatter
 
@@ -222,26 +212,15 @@ _Note: you don’t have to use `.format`—this is just an example! You can use
 
 ## 🏅 Project Goals
 
-1. Support converting any OpenAPI 3.0 or 2.0 (Swagger) schema to TypeScript types, no matter how complicated
+1. Support converting any valid OpenAPI schema to TypeScript types, no matter how complicated.
+1. This library does **NOT** validate your schema, there are other libraries for that.
 1. The generated TypeScript types **must** match your schema as closely as possible (i.e. don’t convert names to
    `PascalCase` or follow any TypeScript-isms; faithfully reproduce your schema as closely as possible, capitalization
    and all)
-1. This library is a TypeScript generator, not a schema validator.
 
 ## 🤝 Contributing
 
-PRs are welcome! Please see our [CONTRIBUTING.md](./CONTRIBUTING.md) guide. Opening an issue beforehand to discuss is
-encouraged but not required.
-
-[glob]: https://www.npmjs.com/package/glob
-[js-yaml]: https://www.npmjs.com/package/js-yaml
-[namespace]: https://www.typescriptlang.org/docs/handbook/namespaces.html
-[npm-run-all]: https://www.npmjs.com/package/npm-run-all
-[openapi-format]: https://swagger.io/specification/#data-types
-[openapi-operationid]: https://swagger.io/specification/#operation-object
-[openapi2]: https://swagger.io/specification/v2/
-[openapi3]: https://swagger.io/specification
-[prettier]: https://npmjs.com/prettier
+PRs are welcome! Please see our [CONTRIBUTING.md](./CONTRIBUTING.md) guide.
 
 ### Contributors ✨
 
@@ -323,7 +302,7 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
     </tr>
   </tbody>
   <tfoot>
-    
+
   </tfoot>
 </table>
 

package.json

@@ -36,6 +36,7 @@
   "homepage": "https://github.com/drwpow/openapi-typescript#readme",
   "scripts": {
     "build": "del dist && tsc",
+    "dev": "tsc --watch",
     "format": "npm run prettier -w .",
     "lint": "eslint .",
     "prepare": "npm run build",