Merge remote-tracking branch 'origin/master' into bugfix/dependabot-alerts

Author: kokovtsev

.gitignore

@@ -1,5 +1,5 @@
 /.idea
-/node_modules
+node_modules
 /.vscode
 /test/out
 /specs

CHANGELOG.md

@@ -1,4 +1,4 @@
-# [2.0.0-alpha.24](https://github.com/devexperts/swagger-codegen-ts/compare/v2.0.0-alpha.23...v2.0.0-alpha.24) (2020-12-24)
+# [2.0.0-alpha.25](https://github.com/devexperts/swagger-codegen-ts/compare/v2.0.0-alpha.24...v2.0.0-alpha.25) (2021-05-25)
 
 
 ### Bug Fixes
@@ -8,6 +8,8 @@
 
 ### Features
 
+* **asyncapi:** channel parameters ([33ea85d](https://github.com/devexperts/swagger-codegen-ts/commit/33ea85d))
+* support binary and text responses for 2.0 spec ([da355db](https://github.com/devexperts/swagger-codegen-ts/commit/da355db))
 * Support headers ([#133](https://github.com/devexperts/swagger-codegen-ts/issues/133)) ([24b70fa](https://github.com/devexperts/swagger-codegen-ts/commit/24b70fa)), closes [#57](https://github.com/devexperts/swagger-codegen-ts/issues/57)
 
 

README.md

@@ -1,12 +1,66 @@
 [![Build Status](https://travis-ci.org/devexperts/swagger-codegen-ts.svg?branch=master)](https://travis-ci.org/devexperts/swagger-codegen-ts)
- 
-### FAQ
-  1. **Why don't spec codecs reuse common parts?**
-   
-     That's because different versions of specs refer to different versions of [JSON Schema](http://json-schema.org) and they are generally not the same. We would like to avoid maintaining JSON Schema composition in this project. (for now)  
 
-### Contributions
-- use https://www.conventionalcommits.org/en/v1.0.0-beta.2/
+# Typesafe OpenAPI generator for TypeScript
 
-### Publish
-`npm version major|minor|patch`
+## Features
+* Generates client code from **OpenAPI 3.0, 2.0** (aka Swagger) and **AsyncAPI** specs
+* **Pluggable HTTP clients:** can use `fetch`, `Axios` or any other library
+* **Flexible response types:** works with Promises and reactive streams like RxJS
+* **Runtime type checks:** validates server responses against the spec
+* Written in **pure TypeScript** using [`fp-ts`](https://github.com/gcanti/fp-ts) and [`io-ts`](https://github.com/gcanti/io-ts) libraries
+
+## Demo code
+
+> The examples below refer to the [Pet Store OpenAPI 3.0 schema](https://petstore3.swagger.io/).
+
+After running the codegen, interacting with a REST API may be as simple as this:
+
+```typescript
+import { petController as createPetController } from "./src/generated/petstore.json/paths/PetController";
+import { Pet } from "./src/generated/petstore.json/components/schemas/Pet";
+
+// Creating a controller, see the "HTTP Clients" wiki page for more details
+const petController = createPetController({ httpClient: fetchHttpClient });
+
+// The returned object is guaranteed to be a valid `Pet`
+const createdPet: Promise<Pet> = petController.addPet({
+  body: {
+    // The parameters are statically typed, IntelliSense works, too
+    name: "Spotty",
+    photoUrls: [],
+  },
+});
+```
+
+More usage scenarios are supported - check the [usage page](./docs/usage/generated-code.md) for more detail.
+
+## Installation
+
+1. Make sure the peer dependencies are installed, then install the codegen itself:
+   ```
+   yarn add typescript fp-ts io-ts io-ts-types
+   yarn add -D @devexperts/swagger-codegen-ts
+   ```
+
+2. Create a console script that would invoke the `generate` function, passing the options such as path to the schema file and the output directory.
+See the [Generators](docs/usage/api.md) page for the API reference, and [examples/generate](examples/generate) for sample scripts.
+
+3. In most cases, you might want to include the code generation step into the build and local launch scripts. Example:
+   ```diff
+   /* package.json */
+
+     "scripts": {
+   +   "generate:api": "ts-node scripts/generate-api.ts",
+   -   "start": "react-scripts start",
+   +   "start": "yarn generate:api && react-scripts start",
+   -   "build": "react-scripts build"
+   +   "build": "yarn generate:api && react-scripts build"
+     }
+   ```
+
+## Contributing
+
+* Feel free to file bugs and feature requests in [GitHub issues](https://github.com/devexperts/swagger-codegen-ts/issues/new).
+* Pull requests are welcome - please use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0-beta.2/).
+
+Please read the [Contributors Guide](./docs/development/contributors-guide.md) for more information.

docs/development/clients.md

@@ -0,0 +1,34 @@
+# Creating HTTP Clients
+
+The code generated by OpenAPI and AsyncAPI generators requires the user to provide an `HTTPClient` or `WebSocketClient` instance respectively.
+
+The original intent is to create such instances in the consumer's application; however, some predefined clients may be added in the future. This guide describes basic steps to create one.
+
+### Defining a return type
+
+In order to support the desired return type, the generated code must know how to perform some basic operations over that type, such as creating a "successful" or "failed" response object, or applying a given transform function to the response. These operations are abstracted via the [`MonadThrow`](https://gcanti.github.io/fp-ts/modules/MonadThrow.ts.html) interface from the `fp-ts` library.
+
+Some common types already have corresponding `Monad` implementations, while for others you might have to implement one from scratch. For an example of how this can be done and what functions are required, check how the `Monad` is implemented for RxJS's `Observable` in the [`fp-ts-rxjs`](https://github.com/gcanti/fp-ts-rxjs/blob/master/src/Observable.ts) package.
+
+### Implementing the actual HTTP requests logic
+
+Once the `Monad` implementation is available, just two methods need to be added to form a working `HTTPClient`: `throwError` and `request`. As can be seen from their signatures, they create a "failed" response and make actual HTTP calls, respectively.
+
+Considering the above, an `HTTPClient` for RxJS could be defined as follows:
+
+```typescript
+import { Monad } from "fp-ts-rxjs/lib/Observable";
+import { throwError } from "rxjs";
+
+const rxjsHttpClient: HTTPClient1<"Observable"> = {
+  ...Monad,
+  request: (req) => {
+    return ajax({
+      url: req.url,
+      method: req.method,
+      // add the logic to handle `req.body` and other parameters
+    }).pipe();
+  },
+  throwError,
+};
+```

docs/development/contributors-guide.md

@@ -0,0 +1,13 @@
+# Contributors Guide
+
+Thanks for your attention and efforts to improve the codegen!
+
+Here are some resources to help you getting familiar with the code base.
+
+* [Development: Overview](./overview.md)
+
+# Testing
+
+# Submitting changes
+
+# Code style and conventions

docs/development/overview.md

@@ -0,0 +1,11 @@
+# Development: Overview
+
+TODO: describe the architecture and data flows
+
+### FAQ
+  1. **Why don't spec codecs reuse common parts?**
+   
+     That's because different versions of specs refer to different versions of [JSON Schema](http://json-schema.org) and they are generally not the same. We would like to avoid maintaining JSON Schema composition in this project. (for now)  
+
+### Publish
+`npm version major|minor|patch`

docs/usage/api.md

@@ -0,0 +1,22 @@
+# API
+
+The single entry point to the generator is the `generate` function:
+
+```typescript
+import { generate } from "@devexperts/swagger-codegen-ts";
+import { OpenapiObjectCodec } from "@devexperts/swagger-codegen-ts/dist/schema/3.0/openapi-object";
+import { serialize } from "@devexperts/swagger-codegen-ts/dist/language/typescript/3.0";
+
+generate({
+  spec: path.resolve(__dirname, "petstore.json"),
+  out: path.resolve(__dirname, "src/generated"),
+  language: serialize,
+  decoder: OpenapiObjectCodec,
+});
+```
+
+See the typedocs for more info about the options.
+
+# CLI
+
+Not implemented yet - PRs are highly welcome!

docs/usage/clients.md

@@ -0,0 +1,8 @@
+# Clients Reference
+
+Different projects have slightly different requirements regarding the error handling, request and response processing and other logic.
+These requirements should be implemented as an `HTTPClient` instance, which in turn is provided to the generated controllers.
+
+Resources:
+- For developing a custom `HTTPClient`, please refer to [Developers Guide - HTTP clients](../development/clients.md);
+- The repository contains a few [examples](../../examples/clients) of HTTPClient implementation for common libraries;

docs/usage/generated-code.md

@@ -0,0 +1,102 @@
+# Using the generated code
+
+> The examples below refer to the [Pet Store OpenAPI 3.0 schema](https://petstore3.swagger.io/).
+
+## Basic example: using a single controller
+
+In the most basic scenario, you may need just a single **controller** from the generated code. In this case, the code is as simple as this:
+
+```typescript
+import { petController as createPetController } from "./src/generated/petstore.json/paths/PetController";
+import { Pet } from "./src/generated/petstore.json/components/schemas/Pet";
+
+// Creating a controller, see the "HTTP Clients" wiki page for more details
+const petController = createPetController({ httpClient: fetchHttpClient });
+
+// The returned object is guaranteed to be a valid `Pet`
+const createdPet: Promise<Pet> = petController.addPet({
+  body: {
+    // The parameters are statically typed, IntelliSense works, too
+    name: "Spotty",
+    photoUrls: [],
+  },
+});
+```
+
+## The `controllers` object
+
+In most projects, the generated code includes more than one controller. Sometimes it's handy to have a single entry points to all of them - for this purpose, the `controllers` object is created by the generator:
+
+```typescript
+import { controllers } from "./src/generated/petstore.json/paths/paths";
+
+const api = controllers({ httpClient: fetchHttpClient });
+const pets = api.petController.findPetsByStatus({
+  query: { status: some("available") },
+});
+// api.userController and api.storeController are also available
+```
+
+## Plugging different HTTP clients
+
+Generated functions may be instructed to return any generic type with one or two type arguments, for example `Promise<Response>` or `Observable<Either<Error, Response>>`. The return type is specified by providing a corresponding **client**. In the example below, providing an `rxjsHttpClient` makes the `petController` return RxJS's `Observable`:
+
+```typescript
+import { Observable } from "rxjs";
+
+// Now create another controller returning an RxJS stream
+const petRxjsController = createPetController({ httpClient: rxjsHttpClient });
+const createdPet$: Observable<Pet> = petRxjsController.addPet({
+  body: {
+    name: "Spotty",
+    photoUrls: [],
+  },
+});
+```
+
+The list of bundled clients and more information can be found in the [Clients](./clients.md) page.
+
+## Using [`RemoteData`](https://github.com/devexperts/remote-data-ts)
+
+The codegen provides first class support for the `RemoteData<Error, Response>` type, making it easier to build complex logic on top of the generated controllers.
+
+```typescript
+const petRDController = createPetController({ httpClient: liveDataHttpClient });
+/**
+ * `LiveData<E, A> = Observable<RemoteData<E, A>>`
+ *
+ * Emits `pending` when the request is started,
+ * then `success(Pet)` or `failure(Error)` upon completion.
+ */
+const createdPet$: LiveData<Error, Pet> = petRDController.addPet({
+  body: {
+    name: "Spotty",
+    photoUrls: [],
+  },
+});
+```
+
+## Validation utils
+
+Each schema defined in the spec produces a TS type and an `io-ts` codec, which can be used for runtime type checking in the application code:
+
+```typescript
+import { either } from "fp-ts";
+import { pipe } from "fp-ts/function";
+import { User, UserIO } from "./src/generated/petstore.json/components/schemas/User";
+
+pipe(
+    UserIO.decode(JSON.parse(localStorage.getItem('PetStore.user'))),
+    either.fold(
+        error => {
+            console.log('The user record is not valid');
+        },
+        (user: User) => {
+            console.log(`Was previously logged in as: ${user.email}`);
+        }
+    )
+);
+```
+
+Learn more on the `Either` type: [Getting started with fp-ts: Either vs Validation](https://dev.to/gcanti/getting-started-with-fp-ts-either-vs-validation-5eja)
+

examples/.gitignore

@@ -0,0 +1 @@
+/out/