chore: documentation (#108)

* chore: documentation

* Extend "Getting Started" section

* Add warning about code re-generation

* Add spacing before warning

* refactor

---------

Co-authored-by: ANDREYDEN <[email protected]>

Author: needim

README.md

@@ -1,32 +1,80 @@
+<br>
+<br>
+<br>
 <div align="center" style="margin-bottom: 16px">
   <img src="openapi-codegen-logo.svg" width="400px" />
 </div>
+<br>
+<br>
+
+  <div align="center">
+    <a href="https://www.npmjs.com/package/@openapi-codegen/cli">
+      <img alt="npm" src="https://img.shields.io/npm/v/@openapi-codegen/cli.svg?style=for-the-badge">
+    </a>
+    <a href="https://github.com/fabien0102/openapi-codegen/blob/main/LICENCE.md">
+      <img alt="Read the documentation" src="https://img.shields.io/npm/l/@openapi-codegen/cli.svg?style=for-the-badge">
+    </a>
+<br>
+<br>
+    Tooling to give you full type-safety around OpenAPI specs.
+  
+  </div>
+
+<br>
+
+### You can generate
+
+- TypeScript types
+- Type-safe Generic Fetchers
+- Type-safe React Query hooks (https://github.com/tanstack/query)
 
-[![npm](https://img.shields.io/npm/v/@openapi-codegen/cli.svg?style=for-the-badge)](https://www.npmjs.com/package/@openapi-codegen/cli)
-[![License](https://img.shields.io/npm/l/@openapi-codegen/cli.svg?style=for-the-badge)](https://github.com/fabien0102/openapi-codegen/blob/main/LICENSE)
+## Getting started
 
-Tooling to give you full type-safety around OpenAPI specs.
+1. **Initialize the generator**
 
-**For frontend:**
+   ```bash
+   $ npx @openapi-codegen/cli init
+   ```
+   
+   <img style="max-width: 400px" src="https://user-images.githubusercontent.com/271912/194000679-5a4501b8-5fc0-430c-9217-028bf91a5dcd.gif">
 
-This will give you full auto-completion and type-safety of your APIs
+   If you wish to change any of the selections made, you can do so in the generated `openapi-codegen.config.ts` file later..
 
-**For backend: (in coming)**
+2. **Start Generation**
 
-This will generate everything you need to deliver a perfect API, spec driven.
+   ```bash
+   $ npx openapi-codegen gen {namespace}
+   ```
+   After the code generation is done, you will notice the following files:
 
-## Getting started
+   - `{namespace}Fetcher.ts` - defines a function that will make requests to your API.
+   - `{namespace}Context.tsx` - the context that provides `{namespace}Fetcher` to other components.
+   - `{namespace}Components.tsx` - generated React Query components (if you selected React Query as part of initialization).
+   - `{namespace}Schemas.ts` - the generated Typescript types from the provided Open API schemas.
 
-```bash
-$ npm i -D @openapi-codegen/{cli,typescript}
-$ npx openapi-codegen init
-```
+   &nbsp;
+
+   > **Warning**
+   > 
+   > If `{namespace}Fetcher.ts` or `{namespace}Context.tsx` already exist in the output folder, they will not be replaced. However, `{namespace}Components.tsx` and `{namespace}Schemas.ts` will be re-generated each time based on the Open API spec file provided.
+
+3. **Configure the Fetcher** (optional)
 
-Follow the steps, this will generate a configuration file for you (openapi-codegen.config.ts).
+   After the first step you should see a file called `{namespace}Fetcher.ts` in your ouput directory. This file
 
-You should have a bunch of types / components ready to be used.
+   By default it uses the built-in Fetch API, you are free to change this to your fetching library of choice (Axios, Got etc.)
 
-Note: The generated `{namespace}Fetcher.ts` assume a global `fetch`, if you want to use this in a nodejs environment, please update this file (this is just a template)
+   If your Open API spec contains a configured server, then the base URL for all requests will default to that server's URL. If no such configuration exists, you'll need to specify the base URL value.
+
+4. **Install and Configure React Query** (optional)
+
+   If during generator setup you picked `> React Query components`, then you will need to install and configure React Query in order for the generated React hooks to work properly:
+
+   - Install the library
+     ```bash
+     npm i @tanstack/react-query
+     ```
+   - Wire up the `QueryClient` as described [here](https://tanstack.com/query/v4/docs/adapters/react-query).
 
 ## Philosophy
 
@@ -81,27 +129,32 @@ SignUpInput:
 
 OpenAPI Codegen will be able to generate all the relevant validation (or at least give you the choice to do it).
 
-Note: You can also attach any custom logic by using the `x-*` tag, the possibilities are endless!
+> **Note**
+> You can also attach any custom logic by using the `x-*` tag, the possibilities are endless!
 
 ### Frontend side
 
 Having to reverse engineer a backend response is the least productive/fun task ever! However, given a nice OpenAPI specs, we can actually generate nicely typed code for you that lets you interact with your API in a safe manner.
 
-Taking React as example, calling an API can be as simple as this:
+Taking React as example, calling an API can be as simple as this: _(this hooks are using **Tanstack Query** under the hood)_
 
 ```tsx
 import { useListPets } from "./petStore/petStoreComponents"; // <- output from openapi-codegen
 
-const App = () => {
+const Example = () => {
   const { data, loading, error } = useListPets();
 
   // `data` is fully typed and have all documentation from OpenAPI
 };
 ```
 
+> **Note**
+> You can also check this blog post about using generated hooks in React https://xata.io/blog/openapi-typesafe-react-query-hooks
+
 And since this generated from the specs, everything is safe at build time!
 
-Note: If you can’t trust your backend, some runtime validation can be useful to avoid surprises in production 😅
+> **Note**
+> If you can’t trust your backend, some runtime validation can be useful to avoid surprises in production 😅
 
 ## Configuration