- Updating documentation

Author: ferdikoomen

Diff for: README.md

@@ -0,0 +1,13 @@
+# Angular support
+
+Lorem
+
+`openapi --input ./spec.json --output ./generated --client angular`
+
+This has been tested with the following versions:
+
+```
+"@angular/common": "13.1.3",
+"@angular/core": "13.1.3",
+"rxjs": "7.5.2",
+```

Diff for: docs/angular-support.md

@@ -0,0 +1,35 @@
+# Arguments vs. Object style
+
+**Flag:** `--useOptions`
+
+There's no [named parameter](https://en.wikipedia.org/wiki/Named_parameter) in JavaScript or TypeScript, because of
+that, we offer the flag `--useOptions` to generate code in two different styles.
+
+**Argument style:**
+```typescript
+const createUser = (name: string, password: string, type?: string, address?: string) => {
+    // ...
+};
+
+// Usage
+createUser('Jack', '123456', undefined, 'NY US');
+```
+
+**Object style:**
+```typescript
+const createUser = ({ name, password, type, address }: {
+    name: string,
+    password: string,
+    type?: string
+    address?: string
+}) => {
+    // ...
+};
+
+// Usage
+createUser({
+    name: 'Jack',
+    password: '123456',
+    address: 'NY US'
+});
+```

Diff for: docs/arguments-vs-object-style.md

@@ -0,0 +1,24 @@
+# Authorization
+
+The OpenAPI generator supports Bearer Token authorization. In order to enable the sending
+of tokens in each request you can set the token using the global OpenAPI configuration:
+
+```typescript
+import { OpenAPI } from './generated';
+
+OpenAPI.TOKEN = 'some-bearer-token';
+```
+
+Alternatively, we also support an async method that provides the token for each request.
+You can simply assign this method to the same `TOKEN `property in the global OpenAPI object.
+
+```typescript
+import { OpenAPI } from './generated';
+
+const getToken = async () => {
+    // Some code that requests a token...
+    return 'SOME_TOKEN';
+};
+
+OpenAPI.TOKEN = getToken;
+```

Diff for: docs/authorization.md

@@ -0,0 +1,18 @@
+# Axios support
+
+This tool allows you to generate a client based on the [`Axios`](https://www.npmjs.com/package/axios) client.
+The advantage of the Axios client is that it works in both Node.js and Browser based environments.
+If you want to generate the Axios based client then you can specify `--client axios` in the openapi call:
+
+`openapi --input ./spec.json --output ./generated --client axios`
+
+The only downside is that this client needs some additional dependencies to work (due to the missing FormData
+classes in Node.js).
+
+```
+npm install axios --save-dev
+npm install [email protected] --save-dev
+```
+
+In order to compile the project and resolve the imports, you will need to enable the `allowSyntheticDefaultImports`
+in your `tsconfig.json` file.

Diff for: docs/axios-support.md

@@ -0,0 +1,19 @@
+# Babel support
+
+If you use enums inside your models / definitions then those enums are by default inside a namespace with the same name
+as your model. This is called declaration merging. However, the [@babel/plugin-transform-typescript](https://babeljs.io/docs/en/babel-plugin-transform-typescript)
+does not support these namespaces, so if you are using babel in your project please use the `--useUnionTypes` flag
+to generate union types instead of traditional enums. More info can be found here: [Enums vs. Union Types](#enums-vs-union-types---useuniontypes).
+
+**Note:** If you are using Babel 7 and Typescript 3.8 (or higher) then you should enable the `onlyRemoveTypeImports` to
+ignore any 'type only' imports, see https://babeljs.io/docs/en/babel-preset-typescript#onlyremovetypeimports for more info
+
+```javascript
+module.exports = {
+    presets: [
+        ['@babel/preset-typescript', {
+            onlyRemoveTypeImports: true,
+        }],
+    ],
+};
+```

Diff for: docs/babel-support.md

@@ -0,0 +1,62 @@
+# Basic usage
+
+```
+$ openapi --help
+
+  Usage: openapi [options]
+
+  Options:
+    -V, --version             output the version number
+    -i, --input <value>       OpenAPI specification, can be a path, url or string content (required)
+    -o, --output <value>      Output directory (required)
+    -c, --client <value>      HTTP client to generate [fetch, xhr, node, axios, angular] (default: "fetch")
+    --name <value>            Custom client class name
+    --useOptions              Use options instead of arguments
+    --useUnionTypes           Use union types instead of enums
+    --exportCore <value>      Write core files to disk (default: true)
+    --exportServices <value>  Write services to disk (default: true)
+    --exportModels <value>    Write models to disk (default: true)
+    --exportSchemas <value>   Write schemas to disk (default: false)
+    --indent <value>          Indentation options [4, 2, tab] (default: "5")
+    --postfix <value>         Service name postfix (default: "Service")
+    --request <value>         Path to custom request file
+    -h, --help                display help for command
+
+  Examples
+    $ openapi --input ./spec.json --output ./generated
+```
+
+
+## Example
+
+**package.json**
+```json
+{
+    "scripts": {
+        "generate": "openapi --input ./spec.json --output ./generated"
+    }
+}
+```
+
+**NPX**
+
+```
+npx openapi-typescript-codegen --input ./spec.json --output ./generated
+```
+
+**Node.js**
+
+```javascript
+const OpenAPI = require('openapi-typescript-codegen');
+
+OpenAPI.generate({
+    input: './spec.json',
+    output: './generated',
+});
+
+// Or by providing the content of the spec directly 🚀
+OpenAPI.generate({
+    input: require('./spec.json'),
+    output: './generated',
+});
+```

Diff for: docs/basic-usage.md

@@ -0,0 +1,27 @@
+# Client instances
+
+**Flag:** `--name`
+
+The OpenAPI generator allows creation of client instances to support the multiple backend services use case.
+The generated client uses an instance of the server configuration and not the global `OpenAPI` constant.
+To generate a client instance, set a custom name to the client class, use `--name` option.
+
+```
+openapi --input ./spec.json --output ./generated ---name AppClient
+```
+
+The generated client will be exported from the `index` file and can be used as shown below:
+
+```typescript
+// Create the client instance with server and authentication details
+const appClient = new AppClient({
+    BASE: 'http://server-host.com',
+    TOKEN: '1234',
+});
+
+// Use the client instance to make the API call
+const response = await appClient.organizations.createOrganization({
+  name: 'OrgName',
+  description: 'OrgDescription',
+});
+```

Diff for: docs/client-instances.md

@@ -0,0 +1,45 @@
+# Enum with custom names and descriptions
+
+You can use `x-enum-varnames` and `x-enum-descriptions` in your spec to generate enum with custom names and descriptions.
+It's not in official [spec](https://github.com/OAI/OpenAPI-Specification/issues/681) yet. But it's a supported extension
+that can help developers use more meaningful enumerators.
+```json
+{
+    "EnumWithStrings": {
+        "description": "This is a simple enum with strings",
+        "enum": [
+            0,
+            1,
+            2
+        ],
+        "x-enum-varnames": [
+            "Success",
+            "Warning",
+            "Error"
+        ],
+        "x-enum-descriptions": [
+            "Used when the status of something is successful",
+            "Used when the status of something has a warning",
+            "Used when the status of something has an error"
+        ]
+    }
+}
+```
+
+Generated code:
+```typescript
+enum EnumWithStrings {
+    /*
+    * Used when the status of something is successful
+    */
+    Success = 0,
+    /*
+    * Used when the status of something has a warning
+    */
+    Waring = 1,
+    /*
+    * Used when the status of something has an error
+    */
+    Error = 2,
+}
+```

Diff for: docs/custom-enums.md

@@ -0,0 +1,52 @@
+# Enums vs. Union types
+
+**Flag:**  `--useUnionTypes`
+
+The OpenAPI spec allows you to define [enums](https://swagger.io/docs/specification/data-models/enums/) inside the
+data model. By default, we convert these enums definitions to [TypeScript enums](https://www.typescriptlang.org/docs/handbook/enums.html).
+However, these enums are merged inside the namespace of the model, this is unsupported by Babel, [see docs](https://babeljs.io/docs/en/babel-plugin-transform-typescript#impartial-namespace-support).
+Because we also want to support projects that use Babel [@babel/plugin-transform-typescript](https://babeljs.io/docs/en/babel-plugin-transform-typescript),
+we offer the flag `--useUnionTypes` to generate [union types](https://www.typescriptlang.org/docs/handbook/unions-and-intersections.html#union-types)
+instead of the traditional enums. The difference can be seen below:
+
+**Enums:**
+```typescript
+// Model
+export type Order = {
+    id?: number;
+    quantity?: number;
+    status?: Order.status;
+};
+
+export namespace Order {
+    export enum status {
+        PLACED = 'placed',
+        APPROVED = 'approved',
+        DELIVERED = 'delivered',
+    }
+}
+
+// Usage
+const order: Order = {
+    id: 1,
+    quantity: 40,
+    status: Order.status.PLACED,
+};
+```
+
+**Union Types:**
+```typescript
+// Model
+export type Order = {
+    id?: number;
+    quantity?: number;
+    status?: 'placed' | 'approved' | 'delivered';
+};
+
+// Usage
+const order: Order = {
+    id: 1,
+    quantity: 40,
+    status: 'placed',
+};
+```

Diff for: docs/enum-vs-union-types.md

@@ -0,0 +1,26 @@
+# External references
+
+Local references to schema definitions (those beginning with `#/definitions/schemas/`)
+will be converted to type references to the equivalent, generated top-level type.
+
+The OpenAPI generator also supports external references, which allows you to break
+down your openapi.yml into multiple sub-files, or incorporate third-party schemas
+as part of your types to ensure everything is able to be TypeScript generated.
+
+External references may be:
+* *relative references* - references to other files at the same location e.g.
+  `{ $ref: 'schemas/customer.yml' }`
+* *remote references* - fully qualified references to another remote location
+  e.g. `{ $ref: 'https://myexampledomain.com/schemas/customer_schema.yml' }`
+
+  For remote references, both files (when the file is on the current filesystem)
+  and http(s) URLs are supported.
+
+External references may also contain internal paths in the external schema (e.g.
+`schemas/collection.yml#/definitions/schemas/Customer`) and back-references to
+the base openapi file or between files (so that you can reference another
+schema in the main file as a type of an object or array property, for example).
+
+At start-up, an OpenAPI or Swagger file with external references will be "bundled",
+so that all external references and back-references will be resolved (but local
+references preserved).

Diff for: docs/external-references.md

@@ -0,0 +1,23 @@
+# Node-Fetch support
+
+By default, this tool will generate a client that is compatible with the (browser based) Fetch API.
+However, this client will not work inside the Node.js environment. If you want to generate the Node.js compatible
+client then you can specify `--client node` in the openapi call:
+
+`openapi --input ./spec.json --output ./generated --client node`
+
+This will generate a client that uses [`node-fetch`](https://www.npmjs.com/package/node-fetch) internally. However,
+in order to compile and run this client, you might need to install the `[email protected]` dependencies.
+
+> Since version 3.x [`node-fetch`](https://www.npmjs.com/package/node-fetch) switched to ESM only,
+> breaking many CommonJS based toolchains (like Jest). Right now we do not support this new version!
+
+```
+npm install @types/[email protected] --save-dev
+npm install [email protected] --save-dev
+npm install [email protected] --save-dev
+npm install [email protected] --save-dev
+```
+
+In order to compile the project and resolve the imports, you will need to enable the `allowSyntheticDefaultImports`
+in your `tsconfig.json` file.

Diff for: docs/node-fetch-support.md

@@ -0,0 +1,37 @@
+# Nullable props (OpenAPI v2)
+
+In the OpenAPI v3 spec you can create properties that can be `NULL`, by providing a `nullable: true` in your schema.
+However, the v2 spec does not allow you to do this. You can use the unofficial `x-nullable` in your specification
+to generate nullable properties in OpenApi v2.
+
+```json
+{
+    "ModelWithNullableString": {
+        "required": [
+            "requiredProp"
+        ],
+        "description": "This is a model with one string property",
+        "type": "object",
+        "properties": {
+            "prop": {
+                "description": "This is a simple string property",
+                "type": "string",
+                "x-nullable": true
+            },
+            "requiredProp": {
+                "description": "This is a simple string property",
+                "type": "string",
+                "x-nullable": true
+            }
+        }
+    }
+}
+```
+
+Generated code:
+```typescript
+export type ModelWithNullableString = {
+    prop?: string | null;
+    requiredProp: string | null;
+};
+```