Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/superfaceai/openapi-linter
Is your OpenAPI Spec ready for SDK generators?
https://github.com/superfaceai/openapi-linter
oas openapi openapi-validation openapi2 openapi3 swagger
Last synced: 8 days ago
JSON representation
Is your OpenAPI Spec ready for SDK generators?
- Host: GitHub
- URL: https://github.com/superfaceai/openapi-linter
- Owner: superfaceai
- License: mit
- Created: 2022-08-30T10:24:31.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2023-07-19T11:32:46.000Z (over 1 year ago)
- Last Synced: 2024-05-28T20:06:21.996Z (6 months ago)
- Topics: oas, openapi, openapi-validation, openapi2, openapi3, swagger
- Language: TypeScript
- Homepage:
- Size: 717 KB
- Stars: 12
- Watchers: 5
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# OpenAPI Linter
[](https://github.com/superfaceai/openapi-linter/actions/workflows/main.yml)
[](https://www.npmjs.com/package/@superfaceai/openapi-linter)
[](LICENSE)
[](https://oclif.io)
[](https://github.com/orgs/superfaceai/discussions)
> Is your OpenAPI Spec ready for SDK generators?
OpenAPI Linter is a CLI and a Node.js library to validate OpenAPI specification.
It is based on [Spectral] by Stoplight with [OpenAPI rules](https://meta.stoplight.io/docs/spectral/4dec24461f3af-open-api-rules) with additional rules. The goal of Linter is to check whether the spec contains enough information to generate high quality, well documented SDK.
We use OpenAPI Linter in [Superface Integration Designer][designer], but any client code generator benefits from well written OpenAPI specs.
## Setup
Install from npm globally:
```shell
npm i -g @superfaceai/openapi-linter
```
Now you can use the linter with commands `openapi-linter` or `oal`.
Alternatively you can use the linter without installation with `npx`:
```
npx @superfaceai/openapi-linter lint
```
## CLI commands
- [`openapi-linter lint SPECIFICATIONPATH`](#openapi-linter-lint-specificationpath)
### `openapi-linter lint SPECIFICATIONPATH`
Lints OpenAPI specification using three different parsers/validators.
```
USAGE
$ openapi-linter lint [SPECIFICATIONPATH] [-f yaml|json] [-e error|warning|any]
ARGUMENTS
SPECIFICATIONPATH Path or URL to specification file
FLAGS
-e, --throwOn= [default: error] On which kind of severty error should be thrown. When set to warning
command will throw when there is a result with "warning" or "error" severity.
-f, --fileFormat= Format of specification. Must be "yaml" or "json" when defined
DESCRIPTION
Lints OpenAPI specification using three different parsers/validators.
EXAMPLES
$ oal lint https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml
$ oal lint examples/petstore.yaml
$ oal lint examples/petstore.yaml -e any
$ oal lint examples/petstore.yaml -f yaml
```
## Usage in code
Install the linter as a dependency into your project:
```shell
npm i @superfaceai/openapi-linter
```
Use the `lint` function:
```ts
import { lint } from 'openapi-linter';
// Get specification as string
const specification = await fs.readFile(pathToSpec, { encoding: 'utf-8' });
// Pass specification, its extension ("yaml" or "json") and name
const lintResult = await lint(specification, 'yaml', 'my-spec-name');
//Do something with result
console.log(lintResult);
```
## Related projects
- [Spectral], generic linter for JSON and YAML this project is based on
- [OpenAPI Enforcer](https://openapi-enforcer.com/)
- [OpenAPI Validator](https://github.com/IBM/openapi-validator)
- [OAS Tools](https://oas-tools.github.io/)
- [Redocly CLI](https://github.com/Redocly/redocly-cli)
- [Cherrybomb](https://github.com/blst-security/cherrybomb) (Rust)
- and [many more](https://openapi.tools/)
## Maintainers
- [Jakub Vacek](https://github.com/Jakub-Vacek)
- [Radek Kyselý](https://github.com/kysely)
## License
This project is licensed under the [MIT license](LICENSE).
© 2023 Superface s.r.o.
[spectral]: https://stoplight.io/open-source/spectral
[designer]: https://superface.ai/designer