Skip to content

Latest commit

 

History

History
75 lines (55 loc) · 2.94 KB

README.md

File metadata and controls

75 lines (55 loc) · 2.94 KB

Typesafe OpenAPI generator for TypeScript

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 and io-ts libraries

Demo code

The examples below refer to the Pet Store OpenAPI 3.0 schema.

After running the codegen, interacting with a REST API may be as simple as this:

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 for more detail.

CLI Usage

  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. Use the CLI to generate the client code. Example:

    yarn swagger-codegen-ts -o src/generated petstore-api.yaml

  3. In most cases, you might want to add this command into your package.json and include it into the build and local launch scripts. Example:

    /* package.json */

  "scripts": {
+   "generate:api": "swagger-codegen-ts -o src/generated petstore-api.yaml",
-   "start": "react-scripts start",
+   "start": "yarn generate:api && react-scripts start",
-   "build": "react-scripts build"
+   "build": "yarn generate:api && react-scripts build"
  }

API

You can also create a custom script using the API. The main entry point of the API is the generate function, which accepts options such as path to the schema file and the output directory.

See the Generators page for the API reference, and examples/generate for sample scripts.

Contributing

Please read the Contributors Guide for more information.