Zally: A minimalistic, simple-to-use OpenAPI 2 and 3 linter
Zally is a quality assurance tool. It's a linter for OpenAPI specifications, it performs the following tasks :
- Increases the quality of APIs
- Checks compliance
- Delivers early feedback for API designers
- Ensures the same look-and-feel of APIs
- Supports API-First approach
- Provides best practices and advices
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 has an easy-to-use CLI which 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.
Features
- Support for OpenAPI 3 and (Swagger) OpenAPI 2 specifications
- RESTful API, CLI and Web interface
- Rich Check configuration
- Ignore functionality (
x-zally-ignore
extension) - Java/Kotlin API for new Checks + helper functions
Quick start guide
Trying out Zally is easy. You can build and run the whole Zally stack (web-ui, server and database) by executing:
./build-and-run.sh
Web UI is accessible on http://localhost:8080
; Zally server on http://localhost:8000
Documentation and Manuals
Please consult the following documents for further information:
- Zally Concepts
- How to operate Zally tools
- How to use Zally
- How to develop new Rules
- Building Under Windows Subsystem for Linux
Integrations
- Zally Maven Plugin (unofficial)
Contributing to Zally
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.
Contact
Feel free to join our Gitter room or contact one of the maintainers directly.
Alternatives
Zally is not the only linter for OpenAPI v2 and v3. There is an article comparing different OpenAPI linters.
So why should you choose Zally?
- It supports Zalando's RESTful Guidelines
- It can be used in multiple ways: RESTful API, CLI and Web interface
- Highly customizable (with Kotlin)
License
MIT license with an exception. See license file.
Publish
Prerequisites
- Signing plugin configured
OSSRH_JIRA_USERNAME
andOSSRH_JIRA_PASSWORD
environment variables to access Maven Central Repo are configured
Steps
-
Create a separate branch with a name
release-<release-version>
. -
Update current version in
server/gradle.properties
from-SNAPSHOT
to a final version. -
Update mime types configuration:
./gradlew -q generate-media-types-config --info
-
Commit the updated file to the repository.
-
Release Zally server and API using the command
cd server ./gradlew clean build publishAllPublicationsToMavenRepository
-
Commit
server/gradle.properties
with the release version -
Create a tag
git tag v<release-version> -m "Version <release-version>"
-
Bump version in
server/gradle.properties
to the next-SNAPSHOT
-
Push
release
branch and taggit push origin git push origin <tag-name>
-
Create a Pull Request with the version update
-
Create and publish a release with a new version in GitHub