# swagger2
> Typescript-based tools for working with Swagger v2.0 documents
Latest version **5.0.1** (published 2025-06-10) · MIT license · 0 weekly downloads
## Install
```sh
npm install swagger2
pnpm add swagger2
yarn add swagger2
bun add swagger2
```
## Health
**Score 35/100 (D)** — status: maintenance-mode.
Positive: esm support; no vulnerabilities; has provenance.
Warnings: low downloads; no types.
Negative: stale; low maintenance score.
## Facts
| | |
|---|---|
| Version | 5.0.1 |
| Published | 2025-06-10 |
| First published | 2016-03-10 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM |
| Node | >=22 |
| Dependencies | 3 |
| Unpacked size | 141.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| Author | Carl Ansley |
| Maintainers | carlansley |
| Keywords | swagger, typescript, koa, koa2 |
## Links
- npm: https://www.npmjs.com/package/swagger2
- Repository: https://github.com/carlansley/swagger2
- Homepage: https://github.com/carlansley/swagger2#readme
- Issues: https://github.com/carlansley/swagger2/issues
- npm.io page: https://npm.io/package/swagger2
## Dependencies (3)
- [js-yaml](https://npm.io/package/js-yaml.md) ^4.1.0
- [is-my-json-valid](https://npm.io/package/is-my-json-valid.md) ^2.20.6
- [json-schema-deref-sync](https://npm.io/package/json-schema-deref-sync.md) ^0.14.0
## Alternatives
- [@openai/codex-sdk](https://npm.io/package/@openai/codex-sdk.md) — 731.4K weekly downloads
- [babel-plugin-transform-react-jsx](https://npm.io/package/babel-plugin-transform-react-jsx.md) — 565.0K weekly downloads
- [babel-helper-remove-or-void](https://npm.io/package/babel-helper-remove-or-void.md) — 508.5K weekly downloads
- [@pnpm/store-controller-types](https://npm.io/package/@pnpm/store-controller-types.md) — 186.9K weekly downloads
- [react-native-signature-canvas](https://npm.io/package/react-native-signature-canvas.md) — 155.6K weekly downloads
## Recent versions
- 5.0.1 (latest) — 2025-06-10
- 5.0.1-PR.59-9e10 (beta) — 2025-06-10
- 5.0.0-PR.58-6673 — 2025-06-10
- 4.0.3 — 2022-12-05
- 4.0.2 — 2022-08-19
- 4.0.0 — 2022-08-19
- 3.0.1 — 2022-01-25
- 3.0.0 — 2021-02-08
- 2.0.0 — 2019-10-08
- 1.0.5 — 2019-07-15
- 1.0.4 — 2018-11-21
- 1.0.3 — 2018-11-07
- 1.0.1 — 2018-05-23
- 1.0.0 — 2018-04-05
- 0.0.30 — 2018-03-05
- … 29 more at https://npm.io/package/swagger2/versions
## README
# swagger2
Loading, parsing and validating requests to HTTP services based on Swagger v2.0 documents.
## Benefits
- Fast. Pre-compiled regular expressions and code generation used to validate the inputs and outputs
of Swagger 2.0 operations at run-time.
- Typed. swagger2 is implemented in TypeScript, including a fully annotated TypeScript definition of
the Swagger 2.0 document object. Makes working with Swagger objects more pleasant in the IDE of your
choosing (WebStorm, Atom, etc.).
## Installation
```shell
$ npm add swagger2
```
## Usage
Basic loading and validation of swagger 2.0 document:
```typescript
import * as swagger from 'swagger2';
// load YAML swagger file
const document = swagger.loadDocumentSync('./swagger.yml');
// validate document
if (!swagger.validateDocument(document)) {
throw Error(`./swagger.yml does not conform to the Swagger 2.0 schema`);
}
```
You can compile the document for fast validation of operation requests and responses within
the framework of your choosing. Koa 2 example:
```typescript
let app = new Koa();
//...
app.use(body());
app.use(createKoaMiddleware(document));
//...
function createKoaMiddleware(document: swagger.Document) {
// construct a validation object, pre-compiling all schema and regex required
let compiled = swagger.compileDocument(document);
return async (context, next) => {
if (!context.path.startsWith(document.basePath)) {
// not a path that we care about
await next();
return;
}
let compiledPath = compiled(context.path);
if (compiledPath === undefined) {
// if there is no single matching path, return 404 (not found)
context.status = 404;
return;
}
// check the request matches the swagger schema
let validationErrors = swagger.validateRequest(
compiledPath,
context.method,
context.request.query,
context.request.body,
);
if (validationErrors === undefined) {
// operation not defined, return 405 (method not allowed)
context.status = 405;
return;
}
if (validationErrors.length > 0) {
context.status = 400;
context.body = {
code: 'SWAGGER_REQUEST_VALIDATION_FAILED',
errors: validationErrors,
};
return;
}
// wait for the operation to execute
await next();
// check the response matches the swagger schema
let error = swagger.validateResponse(
compiledPath,
context.method,
context.status,
context.body,
);
if (error) {
error.where = 'response';
context.status = 500;
context.body = {
code: 'SWAGGER_RESPONSE_VALIDATION_FAILED',
errors: [error],
};
}
};
}
```
There is a complete implementation of this example/use-case in the swagger2-koa module,
so if you're using Koa 2 it may make sense to use that instead of swagger2 directly.
## Limitations
- currently only supports synchronous loading of full documents (via swagger.loadDocumentSync)
- does not support validation of file attachments
- does not support validation of mime-types
- requires node v22.0 or above
- is now ESM
## Development
First, grab the source from GitHub.
From within the swagger2 directory, to run tests:
```shell
$ npm install
$ npm test
```
To see code coverage in a web browser:
```shell
$ npm run ci:coverage
$ open coverage/lcov-report/index.html (on Mac)
```
To clean up:
```shell
$ npm run clean
```
## License
MIT
---
_Source: https://npm.io/package/swagger2 · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._