Skip to main content

HTTP Client

Install​

npm install @basketry/typescript-http-client

Basic Usage​

basketry.config.json
{
  "source": "petstore.json",
  "parser": "@basketry/openapi-3",
  "generators": [
    "@basketry/typescript",
    "@basketry/typescript-validators",
    "@basketry/typescript-http-client"
  ],
  "output": "src"
}

File Structure​

This generator will create an http-client.ts file that contains an HTTP client for the API. This client will have methods for each operation defined in the source schema.

my-project/
├── node_modules/
├── src/
│   ├── v1/                  <-- generated
│   │   └── date-utils.ts
│   │   └── http-client.ts   <-- generated
│   │   └── sanitizers.ts
│   │   └── validators.ts
│   │   └── types.ts
│   ├── index.ts
├── .gitignore
├── basketry.config.json
├── package.json
├── petstore.json
└── README.md

Options​

This generator depends on the @basketry/typescript and @basketry/typescript-validators generator and all of their applied options will also apply to files emitted by this generator.

See:

This generator depends on files generated by the @basketry/typescript and @basketry/typescript-validators generators. In most cases, those files will exist within the same directory as the generated http-client.ts file.

By default, the generated code will import its dependencies as follows:

src/v1/http-client.ts
import * as dateUtils from "./date-utils.ts";
import * as sanitizers from "./sanitizers.ts";
import * as validators from "./validators.ts";
import * as types from "./types.ts";

If those modules are located in a different directory, you can use the following options to specify custom import paths. These paths can be any string that you would normally require or import. This can be useful when generated dependencies are distributed as part of a library or package.

dateUtilsImportPath​

  • Type: string - specifies the path for the date-utils import.
basketry.config.json
{
  "source": "petstore.json",
  "parser": "@basketry/openapi-3",
  "generators": [
    "@basketry/typescript",
    "@basketry/typescript-validators",
    "@basketry/typescript-http-client"
  ],
  "output": "src",
  "options": {
    "typescriptHttpClient": {
      "dateUtilsImportPath": "@petstore/sdk/lib/date-utils"
    }
  }
}

This option as configured will now emit the following code at the top of the generated file:

src/v1/http-client.ts
import * as dateUtils from "@petstore/sdk/lib/date-utils";

sanitizersImportPath​

  • Type: string - specifies the path for the sanitizers import.
basketry.config.json
{
  "source": "petstore.json",
  "parser": "@basketry/openapi-3",
  "generators": [
    "@basketry/typescript",
    "@basketry/typescript-validators",
    "@basketry/typescript-http-client"
  ],
  "output": "src",
  "options": {
    "typescriptHttpClient": {
      "sanitizersImportPath": "@petstore/sdk/lib/sanitizers"
    }
  }
}

This option as configured will now emit the following code at the top of the generated file:

src/v1/http-client.ts
import * as sanitizers from "@petstore/sdk/lib/sanitizers";

validatorsImportPath​

  • Type: string - specifies the path for the validators import.
basketry.config.json
{
  "source": "petstore.json",
  "parser": "@basketry/openapi-3",
  "generators": [
    "@basketry/typescript",
    "@basketry/typescript-validators",
    "@basketry/typescript-http-client"
  ],
  "output": "src",
  "options": {
    "typescriptHttpClient": {
      "validatorsImportPath": "@petstore/sdk/lib/validators"
    }
  }
}

This option as configured will now emit the following code at the top of the generated file:

src/v1/http-client.ts
import * as validators from "@petstore/sdk/lib/validators";

typesImportPath​

  • Type: string - specifies the path for the types import.
basketry.config.json
{
  "source": "petstore.json",
  "parser": "@basketry/openapi-3",
  "generators": [
    "@basketry/typescript",
    "@basketry/typescript-validators",
    "@basketry/typescript-http-client"
  ],
  "output": "src",
  "options": {
    "typescriptHttpClient": {
      "typesImportPath": "@petstore/sdk/lib/types"
    }
  }
}

This option as configured will now emit the following code at the top of the generated file:

src/v1/http-client.ts
import * as types from "@petstore/sdk/lib/types";

includeAuthSchemes​

  • Type: boolean - specifies whether authentication scheme options should be defined in the client class constructors. If set to true, the client class constructors will accept an auth object that can be used to authenticate requests. If set to false or not defined, the client class constructors will not accept an auth object.
basketry.config.json
{
  "source": "petstore.json",
  "parser": "@basketry/openapi-3",
  "generators": [
    "@basketry/typescript",
    "@basketry/typescript-validators",
    "@basketry/typescript-http-client"
  ],
  "output": "src",
  "options": {
    "typescriptHttpClient": {
      "includeAuthSchemes": true
    }
  }
}

Examples​

You can use the following examples to see how to use the generated HTTP Client. In both the browser and Node environments, you can pass any method that implements the fetch interface to the service class. You can use the native fetch method, a wrapped version of fetch, or a custom library of your choosing.

Browser​

src/index.ts
import { HttpPetService, PetService } from "./v1/http-client";

const petService: PetService = new HttpPetService(window.fetch.bind(window), {
  root: "https://api.example.com/v1",
});

export default petService;
warning

Note that if you pass window.fetch to a service class, you need to rebind the fetch method to the window object.

If you don't, the fetch method will fail to execute in the browser environment. No request will be sent, and the console will display the error "TypeError: Failed to execute 'fetch' on 'Window': Illegal invocation".

Node​

src/index.ts
import { HttpPetService, PetService } from "./v1/http-client";

const petService: PetService = new PetService(fetch, {
  root: "https://api.example.com/v1",
});

export default petService;