https://github.com/welovecoding/swaxios
A Swagger API client generator based on axios and written in TypeScript. 🌊
https://github.com/welovecoding/swaxios
api-client api-generator axios browser cli code-generation generator hacktoberfest javascript nodejs rest swagger typescript
Last synced: 8 months ago
JSON representation
A Swagger API client generator based on axios and written in TypeScript. 🌊
- Host: GitHub
- URL: https://github.com/welovecoding/swaxios
- Owner: welovecoding
- Created: 2019-04-26T13:03:37.000Z (over 6 years ago)
- Default Branch: main
- Last Pushed: 2025-04-01T01:33:53.000Z (9 months ago)
- Last Synced: 2025-04-15T15:16:33.799Z (8 months ago)
- Topics: api-client, api-generator, axios, browser, cli, code-generation, generator, hacktoberfest, javascript, nodejs, rest, swagger, typescript
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/swaxios
- Size: 1.06 MB
- Stars: 17
- Watchers: 0
- Forks: 0
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
# Swaxios
A [Swagger (OpenAPI v2)][oas2] API client generator based on [axios][axios] and written in [TypeScript][ts].
## Motivation
The Swaxios project automates the creation of an API client for TypeScript applications, which can be used in web browsers and Node.js environments.
At the time of writing this tool (2019-04-26), the [Swagger Codegen project][codegen] only provided separate SDK generators for browsers and Node.js (`typescript-fetch` and `typescript-node`). Unfortunately, the `typescript-fetch` generator for browsers is not compatible with all Node.js applications since the fetch API became globally available only as an [experimental feature in Node.js 18](https://nodejs.org/de/blog/announcements/v18-release-announce/#fetch-experimental) (2022-04-19).
Swaxios offers an API generator that works in both environments (browsers & Node.js 16+) by utilizing the flexible [axios request library][axios]. API calls are routed through axios and can be easily customized using request interceptors.
## Limitations
This library can only work with a valid [OpenAPI Version 2 specification][oas2], which must be in the form of a file or URL. It does not support [OpenAPI Version 3][oas3] specifications.
If you need a generator for Open API v3 specs, you can test `typescript-axios` from [Swagger Codegen][codegen] ([added on 2020-09-21](https://github.com/swagger-api/swagger-codegen-generators/commits/master/src/main/java/io/swagger/codegen/v3/generators/typescript/TypeScriptAxiosClientCodegen.java)).
```bash
java -jar swagger-codegen-cli-3.0.24.jar generate -l typescript-axios -i ./swagger.json -o ./api-client
```
- [Download Swagger Codegen 3.0.24](https://repo1.maven.org/maven2/io/swagger/codegen/v3/swagger-codegen-cli/3.0.24/swagger-codegen-cli-3.0.24.jar) ([Release Notes](https://github.com/swagger-api/swagger-codegen/releases/tag/v3.0.24))
There is also an npm package ([@openapitools/openapi-generator-cli](https://www.npmjs.com/package/@openapitools/openapi-generator-cli)) which exposes this generator. You can use it the following way in your [scripts](https://docs.npmjs.com/cli/using-npm/scripts):
```json
{
"scripts": {
"generate": "openapi-generator-cli generate -i ./swagger.json -g typescript-axios -p \"withoutRuntimeChecks=true,withInterfaces=true\" -o ./api-client"
}
}
```
## Installation
You can install Swaxios globally (`npm i -g swaxios`) or add it to your [devDependencies](https://docs.npmjs.com/files/package.json#devdependencies).
## Usage
Display all CLI options:
```
swaxios --help
```
If you pass an [OpenAPI v2 specification][oas2] (JSON or YAML) to Swaxios, then it generates a fully typed API client for you which uses axios under the hood:
```bash
# Provide a Swagger input file (JSON or YAML)
swaxios -i ./path/to/swagger.json -o ./path/to/output/directory
swaxios -i ./path/to/swagger.yml -o ./path/to/output/directory
# Alternative: Provide a URL to a Swagger endpoint
swaxios -i http://127.0.0.1:3000/documentation-json -o ./path/to/output/directory
```
With the `-f` option, you can force Swaxios to overwrite existing files in the output path:
```bash
swaxios -i ./path/to/swagger.json -o ./path/to/output/directory -f
```
## Examples
You can find many examples of generated API client code in our [snapshots section](./src/test/snapshots).
Here is a basic example:
**`ExchangeService.ts`**
```ts
/* tslint:disable */
/**
* This file was automatically generated by "Swaxios".
* It should not be modified by hand.
*/
import {AxiosInstance, AxiosRequestConfig} from 'axios';
export class ExchangeService {
private readonly apiClient: AxiosInstance;
constructor(apiClient: AxiosInstance) {
this.apiClient = apiClient;
}
deleteExchange = async (id: number): Promise => {
const config: AxiosRequestConfig = {
method: 'delete',
url: `/api/v1/exchange/${id}`,
};
await this.apiClient.request(config);
};
}
```
It has been generated from the following [path](https://swagger.io/docs/specification/2-0/paths-and-operations/):
**`swagger.json`**
```jsonc
{
// ...
"paths": {
"/api/v1/exchange/{id}": {
"delete": {
"consumes": ["application/json"],
"operationId": "deleteExchange",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"type": "number"
}
],
"produces": ["application/json"],
"responses": {
"200": {
"description": ""
}
}
}
}
}
// ...
}
```
## Alternatives
- [OpenAPI TypeScript](https://www.npmjs.com/package/openapi-typescript)
[axios]: https://github.com/axios/axios
[codegen]: https://github.com/swagger-api/swagger-codegen
[oas2]: https://swagger.io/specification/v2/
[oas3]: https://swagger.io/specification/v3/
[ts]: https://www.typescriptlang.org/