Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/swagger-api/swagger-js

Javascript library to connect to swagger-enabled APIs via browser or nodejs
https://github.com/swagger-api/swagger-js

hacktoberfest javascript open-source openapi-specification openapi3 openapi31 rest rest-api swagger swagger-api swagger-js swagger-oss

Last synced: 4 days ago
JSON representation

Javascript library to connect to swagger-enabled APIs via browser or nodejs

Awesome Lists containing this project

README 

        
# Swagger Client 



[![Build Status](https://github.com/swagger-api/swagger-js/actions/workflows/nodejs.yml/badge.svg)](https://github.com/swagger-api/swagger-js/actions)



**Swagger Client** is a JavaScript module that allows you to fetch, resolve, and interact with Swagger/OpenAPI documents.



## New!



**This is the new version of swagger-js, 3.x.** The new version supports Swagger 2.0 as well as OpenAPI 3.



Want to learn more? Check out our [FAQ](docs/migration/migration-2-x-to-3-x.md).



For features known to be missing from 3.x please see the [Graveyard](docs/migration/graveyard-3-x.md).



For the older version of swagger-js, refer to the [*2.x branch*](https://github.com/swagger-api/swagger-js/tree/2.x).



> *The npm package is called `swagger-client` and the GitHub repository is `swagger-js`.

We'll be consolidating that soon. Just giving you the heads-up. You may see references to both names.*



## Compatibility

The OpenAPI Specification has undergone multiple revisions since initial creation in 2010. 

Compatibility between Swagger Client and the OpenAPI Specification is as follows:



Swagger Client Version | Release Date | OpenAPI Spec compatibility             | Notes

------------------ |--------------|----------------------------------------| -----

3.19.x | 2023-01-23   | 2.0, 3.0.0, 3.0.1, 3.0.2, 3.0.3, 3.1.0 | [tag v3.19.0-alpha.3](https://github.com/swagger-api/swagger-js/releases/tag/v3.19.0-alpha.3)

3.10.x | 2020-01-17   | 2.0, 3.0.0, 3.0.1, 3.0.2, 3.0.3        | [tag v3.10.0](https://github.com/swagger-api/swagger-js/tree/v3.10.0)

2.1.32 | 2017-01-12   | 1.0, 1.1, 1.2                          | [tag v2.1.32](https://github.com/swagger-api/swagger-js/tree/v2.1.32). This [release](https://github.com/swagger-api/swagger-js/releases/tag/v2.1.32) is only available on GitHub.



## Anonymized analytics



Swagger Client uses [Scarf](https://scarf.sh/) to collect [anonymized installation analytics](https://github.com/scarf-sh/scarf-js?tab=readme-ov-file#as-a-user-of-a-package-using-scarf-js-what-information-does-scarf-js-send-about-me). These analytics help support the maintainers of this library and ONLY run during installation. To [opt out](https://github.com/scarf-sh/scarf-js?tab=readme-ov-file#as-a-user-of-a-package-using-scarf-js-how-can-i-opt-out-of-analytics), you can set the `scarfSettings.enabled` field to `false` in your project's `package.json`:



```

// package.json

{

  // ...

  "scarfSettings": {

    "enabled": false

  }

  // ...

}

```



Alternatively, you can set the environment variable `SCARF_ANALYTICS` to `false` as part of the environment that installs your npm packages, e.g., `SCARF_ANALYTICS=false npm install`.



## Documentation



#### Usage



- [Installation](docs/usage/installation.md)

- [Tags Interface](docs/usage/tags-interface.md)

- [HTTP client for OAS operations](docs/usage/http-client-for-oas-operations.md)

- [OpenAPI Definition Resolver](docs/usage/openapi-definition-resolver.md)

- [HTTP Client](docs/usage/http-client.md)

- [Swagger Client API](docs/usage/api.md)



#### Development



- [Contributing](https://github.com/swagger-api/.github/blob/master/CONTRIBUTING.md)

- [Setting up](docs/development/setting-up.md)

- [Scripts](docs/development/scripts.md)



#### Migrations 



- [Migration guide](docs/migration/migration-2-x-to-3-x.md)

- [Graveyard](docs/migration/graveyard-3-x.md)



### Runtime 



### Node.js



`swagger-client` requires Node.js `>=12.20.0` and uses different `fetch` implementation depending

on Node.js version.



- `>=12.20.0 <18` - [node-fetch@3](https://www.npmjs.com/package/node-fetch) 

- `>=18` - [native Node.js fetch](https://nodejs.org/dist/latest-v18.x/docs/api/globals.html#fetch)



> NOTE: swagger-client minimum Node.js runtime version aligns with [Node.js Releases](https://nodejs.org/en/about/releases/)

> which means that we can drop support for **EOL** (End Of Life) Node.js versions without doing major version bump.



### Browsers



`swagger-client` works in the latest versions of Chrome, Safari, Firefox, and Edge

and uses [native fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) implementation

provided by each supported browser.



## Security contact



Please disclose any security-related issues or vulnerabilities by emailing [[email protected]](mailto:[email protected]), instead of using the public issue tracker.