Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/carlansley/swagger2
Loading, parsing and validating requests to HTTP services based on Swagger v2.0 documents
https://github.com/carlansley/swagger2
openapi swagger validation
Last synced: about 1 month ago
JSON representation
Loading, parsing and validating requests to HTTP services based on Swagger v2.0 documents
- Host: GitHub
- URL: https://github.com/carlansley/swagger2
- Owner: carlansley
- License: mit
- Created: 2016-03-10T00:12:57.000Z (almost 9 years ago)
- Default Branch: main
- Last Pushed: 2023-01-09T04:28:48.000Z (almost 2 years ago)
- Last Synced: 2024-11-07T01:07:08.777Z (about 2 months ago)
- Topics: openapi, swagger, validation
- Language: TypeScript
- Size: 1000 KB
- Stars: 25
- Watchers: 6
- Forks: 17
- Open Issues: 12
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
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:
```
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:
```
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 v16.0 or above
## 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