zally

Zally: A minimalistic, simple-to-use API linter

Zally brings order to your sea of APIs. Use it to:

enable/disable rules on the server side
configure (some) of your existing rules
implement your own rules in Kotlin

Its standard configuration will check your APIs against the rules defined in Zalando’s RESTful Guidelines, but anyone can use it out-of-the-box.

Zally’s easy-to-use CLI uses the server in the background so that you can check your API on the spot. It also features an intuitive Web UI that shows implemented rules and lints external files and (with its online editor) API definitions.

More about Zally:

Swagger-friendly: accepts Swagger .yaml and JSON formats; includes a server that lints your Swagger files; and parses Swagger files using swagger-parser
Using x-zally-ignore extension in your API definition, you can disable rules for a specific API
Applying rule changes is only necessary in the server component
API-specific code written in Java 8 with Spring Boot for better integration
Rule implementation is optimal/possible in Kotlin

Technical Dependencies

Kotlin and Java 8 (server) with Spring Boot
Golang 1.11+: for CLI
Node.js 7.6+: for web UI

Find additional details here. With Spring 5, we consider using Kotlin also directly on the API side.

Installation and Usage

To give Zally a quick try, first run the server locally and then use the CLI tool.

The Server Readme, CLI Readme and Web UI Readme include more detailed installation steps for each component.

Quick start guide

git clone git@github.com:zalando/zally.git zally
cd zally

# Disable authentication and start a local version of Zally server
cd server
./gradlew clean build
./gradlew bootRun > /dev/null &
cd ..

# Build CLI tool
cd cli/zally
go build
./zally lint /path/to/swagger/definition.yaml

Contributing

Zally welcomes contributions from the open source community. To get started, take a look at our contributing guidelines. Then check our Project Board and Issues Tracker for ideas.

Roadmap

For Zally version 1.2, we’re focusing on:

generating new rules
a new quickstart script
better integration testing approaches

If you have ideas for these items, please let us know.

Contact

Feel free to contact one the maintainers.

License

MIT license with an exception. See license file.