Swagger-JS
New!
This is the new version of swagger-js, 3.x. Want to learn more? Check out our FAQ.
For the older version of swagger-js, refer to the 2.x branch.
Note:
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.
Usage
Prerequisites
- Runtime:
- browser: es5 compatible. IE11+
- node v4.x.x
- Building
- node v6.x.x
Download via npm
npm install swagger-client
Import in code
// Or commonjsconst Swagger =
Import in browser
API
This lib exposes these functionalities:
- Static functions for...
- HTTP Client
- Swagger Spec Resolver ( OAS 2.0 )
- TryItOut Executor
- A constructor with the methods...
- HTTP Client, for convenience
- Swagger Spec Resolver ( OAS 2.0 ), which will use
url
orspec
from the instance - TryItOut Executor, bound to the
http
andspec
instance properties - Tags Interface, also bound to the instance
HTTP Client
Swagger.http(req)
exposes a Fetch-like interface with a twist: allowing url
in the request object so that it can be passed around and mutated. It extends Fetch to support request and response interceptors and performs response & header serialization. This method could be overridden to change how SwaggerJS performs HTTP requests.
// Fetch-like, but support `url`, `query` and `xxxInterceptor`const request = url query method body headers requestInterceptor responseInterceptor userFetch Swagger // InterceptorsSwagger // Custom FetchSwagger
Swagger Specification Resolver
Swagger.resolve({url, spec, http})
resolves $ref
s (JSON-Refs) with the objects they point to.
Swagger
This is done automatically if you use the constructor/methods
TryItOut Executor
An HTTP client for OAS operations, maps an operation and values into an HTTP request.
const params = spec operationId // Either operationId, or you can use pathName + method pathName method parameters // _named_ parameters in an object, eg: { petId: 'abc' } securities // _named_ securities, will only be added to the request, if the spec indicates it. eg: {apiKey: 'abc'} requestContentType responseContentType http // You can also override the HTTP client completely userFetch // Alternatively you can just override the fetch method (if you want to use request.js or some other HttpAgent) // Creates a request object compatible with HTTP client interface.// If `pathName` and `method`, then those are used instead of operationId. This is useful if you're using this dynamically, as `pathName` + `method` are guarenteed to be unique.const res = Swagger // You can also generate just the request ( without executing... )const req = Swagger
Constructor and methods
Resolve the spec and expose some methods that use the resolved spec:
Swagger(url, opts): Promise
- Exposes tags interface (see above)
- Exposes the static functions:
execute
,http
,resolve
and some other minor ones - Exposes
#http
,#execute
and#resolve
bound to the instance
Tags Interface
A client for operations. We're currently using the apis[tag][operationId]:ExecuteFunction
interface, which can be disabled entirely using Swagger({disableInterfaces: true})
if you don't need it.
OperationId's are meant to be unique within spec, if they're not we do the following:
- If a tag is absent, we use
default
as the internal tag - If an operationId is missing, we deduce it from the http method and path, i.e.
${method}${path}
, with non-alphanumeric characters escaped to_
. See these tests (1, 2) for examples. - If an operationId is duplicated across all operationIds of the spec, we rename all of them with numbers after the ID to keep them unique. You should not rely on this, as the renaming is non-deterministic. See this test for an example.
In Browser
Prepare swagger-client.js by npm run build-bundle
Note, browser version exports class SwaggerClient
to global namespace
If you need activate CORS requests, just enable it by withCredentials
property at http
check console in browser's dev. tools
Compatibility
SwaggerJS has some legacy signature shapes.
Execute
Response shape
// swagger-js url method status statusText headers data // The textual content obj // The body object // New shape url method status statusText headers // See note below regarding headers text // The textual content body // The body object
Serializing Headers
By default the instance version of #http
serializes the body and headers.
However, headers pose an issue when there are multiple headers with the same name.
As such we've left the static version of http
to not perform any serialization.
Build
npm installnpm run test # run test npm run test:watch # run test with change watching npm run lint # run lint npm run build # package to release npm run build-dev # package with non-minified dist/index.js (for debugging) npm run build-bundle # build browser version available at .../browser
Migration from 2.x
There has been a complete overhaul of the codebase. For notes about how to migrate coming from 2.x, please see Migration from 2.x
Security contact
Please disclose any security-related issues or vulnerabilities by emailing security@swagger.io, instead of using the public issue tracker.
Graveyard
For features known to be missing from 3.x please see the Graveyard