- Updated documentation

README.md

@@ -22,14 +22,12 @@
 - Supports aborting of requests (cancelable promise pattern)
 - Supports external references using [json-schema-ref-parser](https://github.com/APIDevTools/json-schema-ref-parser/)
 
-
 ## Install
 
 ```
 npm install openapi-typescript-codegen --save-dev
 ```
 
-
 ## Usage
 
 ```
@@ -59,7 +57,6 @@ $ openapi --help
     $ openapi --input ./spec.json --output ./generated --client xhr
 ```
 
-
 Documentation
 ===
 - [Basic usage](docs/basic-usage.md)
@@ -73,7 +70,6 @@ Documentation
 - [Authorization](docs/authorization.md)
 - [External references](docs/external-references.md)
 
-
 Support
 ===
 - [Babel support](docs/babel-support.md)
@@ -81,7 +77,6 @@ Support
 - [Angular support](docs/angular-support.md)
 - [Node-Fetch support](docs/node-fetch-support.md)
 
-
 [npm-url]: https://npmjs.org/package/openapi-typescript-codegen
 [npm-image]: https://img.shields.io/npm/v/openapi-typescript-codegen.svg
 [license-url]: LICENSE

docs/arguments-vs-object-style.md

@@ -6,6 +6,7 @@ There's no [named parameter](https://en.wikipedia.org/wiki/Named_parameter) in J
 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) => {
     // ...
@@ -16,6 +17,7 @@ createUser('Jack', '123456', undefined, 'NY US');
 ```
 
 **Object style:**
+
 ```typescript
 const createUser = ({ name, password, type, address }: {
     name: string,

docs/basic-usage.md

@@ -26,7 +26,6 @@ $ openapi --help
     $ openapi --input ./spec.json --output ./generated
 ```
 
-
 ## Example
 
 **package.json**

docs/custom-enums.md

@@ -3,6 +3,7 @@
 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": {
@@ -27,6 +28,7 @@ that can help developers use more meaningful enumerators.
 ```
 
 Generated code:
+
 ```typescript
 enum EnumWithStrings {
     /*

docs/enum-vs-union-types.md

@@ -10,6 +10,7 @@ we offer the flag `--useUnionTypes` to generate [union types](https://www.typesc
 instead of the traditional enums. The difference can be seen below:
 
 **Enums:**
+
 ```typescript
 // Model
 export type Order = {
@@ -35,6 +36,7 @@ const order: Order = {
 ```
 
 **Union Types:**
+
 ```typescript
 // Model
 export type Order = {

docs/external-references.md

@@ -8,13 +8,15 @@ down your openapi.yml into multiple sub-files, or incorporate third-party schema
 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.
+* *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

docs/nullable-props.md

@@ -29,6 +29,7 @@ to generate nullable properties in OpenApi v2.
 ```
 
 Generated code:
+
 ```typescript
 export type ModelWithNullableString = {
     prop?: string | null;

docs/openapi-object.md

@@ -7,8 +7,8 @@ below you can find the properties and their usage.
 
 ```typescript
 export const OpenAPI: OpenAPIConfig = {
-    BASE: 'http://localhost:3000/my-api',
-    VERSION: '1.0',
+    BASE: 'http://localhost:3000/api',
+    VERSION: '2.0',
     WITH_CREDENTIALS: false,
     CREDENTIALS: 'include',
     TOKEN: undefined,
@@ -19,31 +19,126 @@ export const OpenAPI: OpenAPIConfig = {
 };
 ```
 
-## Properties
+Properties
+===
 
-`OpenAPI.BASE`
-Test
+### `OpenAPI.BASE`
 
-`OpenAPI.VERSION`
-Test
+The base path of the OpenAPI server, this is generated from the spec,
+but can be overwritten to switch servers.
 
-`OpenAPI.WITH_CREDENTIALS`
-Test
+```typescript
+if (process.env === 'development') {
+    OpenAPI.BASE = 'http://staging.company.com:3000/api';
+}
+if (process.env === 'production') {
+    OpenAPI.BASE = '/api';
+}
+```
 
-`OpenAPI.CREDENTIALS`
-Test
+### `OpenAPI.VERSION`
 
-`OpenAPI.TOKEN`
-Test
+The version param in the OpenAPI paths `{api-version}`. The version is taken from the spec,
+but can be updated to call multiple versions of the same OpenAPI backend.
 
-`OpenAPI.USERNAME`
-Test
+### `OpenAPI.WITH_CREDENTIALS`
 
-`OpenAPI.PASSWORD`
-Test
+Similar to the [withCredentials](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/withCredentials)
+property of the XHR specification. When set to true, cross-site requests should be made
+using credentials such as cookies, authorization headers, etc.
 
-`OpenAPI.HEADERS`
-Test
+### `OpenAPI.CREDENTIALS`
 
-`OpenAPI.ENCODE_PATH`
-Test
+Similar to the [credentials](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch#sending_a_request_with_credentials_included)
+property of the Fetch specification. When `OpenAPI.WITH_CREDENTIALS` is set to true,
+this property controls the specific implementation for Fetch and Node-Fetch clients.
+Valid values are: `include`, `omit` and `same-origin`.
+
+### `OpenAPI.TOKEN`
+
+Set the Bearer authentication token to use for the requests. This needs to be a valid
+(non-expired) token, otherwise the request will fail. The property can be updated as often
+as you want, this is useful for scenario's where the token would automatically refresh
+after x minutes. This property also allows you to use an `async` method that will be resolved
+before requests are made.
+
+```typescript
+OpenAPI.TOKEN = 'MY_TOKEN';
+
+OpenAPI.TOKEN = async () => {
+    // Note: loading this from a JSON file is not recommended ;-)
+    const response = await fetch('configuration.json');
+    const { token } = response.json();
+    return token;
+};
+```
+
+### `OpenAPI.USERNAME`
+
+Set the basic authentication username, although not recommended, the basic authentication
+header is still supported. The username and password hash will be calculated by the client
+before sending the request. This property also allows you to use an `async` method that
+will be resolved before requests are made.
+
+```typescript
+OpenAPI.USERNAME = 'john';
+
+OpenAPI.USERNAME = async () => {
+    // Note: loading this from a JSON file is not recommended ;-)
+    const response = await fetch('configuration.json');
+    const { username } = response.json();
+    return username;
+};
+```
+
+### `OpenAPI.PASSWORD`
+
+Set the basic authentication password. See `OpenAPI.USERNAME` for more info.
+
+```typescript
+OpenAPI.PASSWORD = 'welcome123';
+
+OpenAPI.PASSWORD = async () => {
+    // Note: loading this from a JSON file is not recommended ;-)
+    const response = await fetch('configuration.json');
+    const { password } = response.json();
+    return password;
+};
+```
+
+### `OpenAPI.HEADERS`
+
+This property allows you to specify additional headers to send for each request. This can be useful
+for adding headers that are not generated through the spec. Or adding headers for tracking purposes.
+This property also allows you to use an `async` method that will be resolved before requests are made.
+
+```typescript
+OpenAPI.HEADERS = {
+    'x-navigator': window.navigator.appVersion,
+    'x-environment': process.env,
+    'last-modified': 'Wed, 21 Oct 2015 07:28:00 GMT',
+};
+
+OpenAPI.HEADERS = async () => {
+    // Note: loading this from a JSON file is not recommended ;-)
+    const response = await fetch('configuration.json');
+    const { headers } = response.json();
+    return headers;
+};
+```
+
+### `OpenAPI.ENCODE_PATH`
+
+By default, all path parameters are encoded using the `encodeURI` method. This will convert invalid
+URL characters, for example spaces, backslashes, etc. However, you might want to make the encoding
+more strict due to security restrictions. So you can set this to `encodeURIComponent` to encode
+most non-alphanumerical characters to percentage encoding. Or set a customer encoder that just
+replaces some special characters.
+
+```typescript
+OpenAPI.ENCODE_PATH = encodeURIComponent;
+
+OpenAPI.ENCODE_PATH = (value: string) => {
+    return value.replace(':', '_');
+};
+```

test/spec/aap.json

@@ -1,28 +0,0 @@
-{
-    "openapi": "3.0.3",
-    "info": {
-        "title": "Header Problem",
-        "version": "1.0.0"
-    },
-    "paths": {},
-    "components": {
-        "headers": {
-            "Generic-Header": {
-                "description": "Generic-Header description",
-                "schema": {
-                    "type": "string"
-                },
-                "example": "123",
-                "required": true
-            }
-        },
-        "schemas": {
-            "Generic-Schema": {
-                "description": "Generic-Schema description",
-                "type": "string",
-                "example": "234",
-                "required": true
-            }
-        }
-    }
-}