From 71fd3ed54577acaa8e7cedd6cea31ffe2e4df177 Mon Sep 17 00:00:00 2001 From: Ferdi Koomen Date: Fri, 28 Jan 2022 17:15:55 +0100 Subject: [PATCH] - Updated documentation --- README.md | 5 -- docs/arguments-vs-object-style.md | 2 + docs/basic-usage.md | 1 - docs/custom-enums.md | 2 + docs/enum-vs-union-types.md | 2 + docs/external-references.md | 10 ++- docs/nullable-props.md | 1 + docs/openapi-object.md | 137 +++++++++++++++++++++++++----- test/spec/aap.json | 28 ------ 9 files changed, 129 insertions(+), 59 deletions(-) delete mode 100644 test/spec/aap.json diff --git a/README.md b/README.md index 9586daaf..61562c82 100644 --- a/README.md +++ b/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 diff --git a/docs/arguments-vs-object-style.md b/docs/arguments-vs-object-style.md index 85acb504..74ed90a4 100644 --- a/docs/arguments-vs-object-style.md +++ b/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, diff --git a/docs/basic-usage.md b/docs/basic-usage.md index ee834087..ec10b4b3 100644 --- a/docs/basic-usage.md +++ b/docs/basic-usage.md @@ -26,7 +26,6 @@ $ openapi --help $ openapi --input ./spec.json --output ./generated ``` - ## Example **package.json** diff --git a/docs/custom-enums.md b/docs/custom-enums.md index a53d6faa..89fef70f 100644 --- a/docs/custom-enums.md +++ b/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 { /* diff --git a/docs/enum-vs-union-types.md b/docs/enum-vs-union-types.md index 129bbdc2..570aa972 100644 --- a/docs/enum-vs-union-types.md +++ b/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 = { diff --git a/docs/external-references.md b/docs/external-references.md index ce0544b5..06844d3f 100644 --- a/docs/external-references.md +++ b/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 diff --git a/docs/nullable-props.md b/docs/nullable-props.md index 21d1bb48..79456145 100644 --- a/docs/nullable-props.md +++ b/docs/nullable-props.md @@ -29,6 +29,7 @@ to generate nullable properties in OpenApi v2. ``` Generated code: + ```typescript export type ModelWithNullableString = { prop?: string | null; diff --git a/docs/openapi-object.md b/docs/openapi-object.md index 8417fcbd..0ec1ad84 100644 --- a/docs/openapi-object.md +++ b/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(':', '_'); +}; +``` diff --git a/test/spec/aap.json b/test/spec/aap.json deleted file mode 100644 index 00b10459..00000000 --- a/test/spec/aap.json +++ /dev/null @@ -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 - } - } - } -}