Security News
The Dark Side of Open Source
At Node Congress, Socket CEO Feross Aboukhadijeh uncovers the darker aspects of open source, where applications that rely heavily on third-party dependencies can be exploited in supply chain attacks.
@apidevtools/swagger-cli
Advanced tools
Readme
$ref
pointersInstall using npm:
npm install -g @apidevtools/swagger-cli
swagger-cli <command> [options] <file>
Commands:
validate Validates an API definition in Swagger 2.0 or OpenAPI 3.0 format
bundle Bundles a multi-file API definition into a single file
Options:
-h, --help Show help for any command
-v, --version Output the CLI version number
-d, --debug [filter] Show debug output, optionally filtered (e.g. "*", "swagger:*", etc.)
The swagger-cli validate
command will validate your Swagger/OpenAPI definition against the Swagger 2.0 schema or OpenAPI 3.0 Schema. It also performs additional validations against the specification, which will catch some things that aren't covered by the schema, such as duplicate parameters, invalid MIME types, etc.
The command will exit with a non-zero code if the API is invalid.
swagger-cli validate [options] <file>
Options:
--no-schema Do NOT validate against the Swagger/OpenAPI JSON schema
--no-spec Do NOT validate against the Swagger/OpenAPI specification
There is a useful Python tool called pre-commit that can be used to execute a wide suite of pre-commit checks. The swagger-cli validate
command can be integrated as part of a git pre-commit hook by adding the following configuration to the repos
entry of an existing .pre-commit-config.yaml
file.
- repo: https://github.com/APIDevTools/swagger-cli
rev: v2.2.1
hooks:
- id: swagger-validation
args: ["validate", "<path to root swagger>"]
The intention is to point to single root swagger that references multiple swagger definitions. The above hook will execute the swagger-cli validation
against the root swagger anytime that a file matching the pattern .*swagger.*\.(json|yaml|yml)
is modified. Any failures in this validation will prevent the git commit from being processed.
The Swagger and OpenAPI specs allows you to split your API definition across multiple files using $ref
pointers to reference each file. You can use the swagger-cli bundle
command to combine all of those referenced files into a single file, which is useful for distribution or interoperation with other tools.
By default, the swagger-cli bundle
command tries to keep the output file size as small as possible, by only embedding each referenced file once. If the same file is referenced multiple times, then any subsequent references are simply modified to point to the single inlined copy of the file. If you want to produce a bundled file without any $ref
pointers, then add the --dereference
option. This will result in a larger file size, since multiple references to the same file will result in that file being embedded multiple times.
If you don't specify the --outfile
option, then the bundled API will be written to stdout, which means you can pipe it to other commands.
The result of this method by default is written as JSON. It can be changed to YAML with the --type
option, by passing the yaml
value.
swagger-cli bundle [options] <file>
Options:
-o, --outfile <file> The output file
-r, --dereference Fully dereference all $ref pointers
-f, --format <spaces> Formats the output using the given number of spaces
(the default is 2 spaces)
-t, --type <filetype> Defines the output file type. The valid values are: json, yaml
(the default is JSON)
-w, --wrap <column> Set the line length for YAML strings
(the default is no wrapping)
I welcome any contributions, enhancements, and bug-fixes. Open an issue on GitHub and submit a pull request.
To build/test the project locally on your computer:
Clone this repo
git clone https://github.com/APIDevTools/swagger-cli.git
Install dependencies
npm install
Run the tests
npm test
Swagger CLI is 100% free and open-source, under the MIT license. Use it however you want.
This package is Treeware. If you use it in production, then we ask that you buy the world a tree to thank us for our work. By contributing to the Treeware forest you’ll be creating employment for local families and restoring wildlife habitats.
Thanks to these awesome companies for their support of Open Source developers ❤
FAQs
Swagger 2.0 and OpenAPI 3.0 command-line tool
The npm package @apidevtools/swagger-cli receives a total of 322,390 weekly downloads. As such, @apidevtools/swagger-cli popularity was classified as popular.
We found that @apidevtools/swagger-cli demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
At Node Congress, Socket CEO Feross Aboukhadijeh uncovers the darker aspects of open source, where applications that rely heavily on third-party dependencies can be exploited in supply chain attacks.
Research
Security News
The Socket Research team found this npm package includes code for collecting sensitive developer information, including your operating system username, Git username, and Git email.
Security News
OpenJS is warning of social engineering takeovers targeting open source projects after receiving a credible attempt on the foundation.