Version Control for APIs. Optic makes it easy to document your APIs, preven...
Optic helps you ship a great API
Shipping an API is easy -- the REST is hard. We built Optic because every developer/team should be able to get the benefits of OpenAPI, without all the time/effort/costs.
[📋 Documentation for all your APIs](#document-your-existing-apis-in-minutes) ← write your API promises down
[🛑 Prevent breaking changes from shipping](#prevent-breaking-changes-with-api-diffs) ← keep your promises
[✅ Verify your API is working-as-designed (the OpenAPI and implementation are in sync)](#verify-your-api-is-working-as-designed) ← make sure the API works as-designed
[🎨 Build a consistent API that follows your team's standards](#build-a-consistent-api-that-follows-your-teams-standards) ← raise the quality of your API
- npm install -g @useoptic/optic
Document your existing APIs in minutes
Use real API traffic to write your initial OpenAPI specification and correctly patch the spec whenever an API changes.
1. Use the CLI to magically capture traffic optic capture openapi.yaml https://api.github.com OR provide a HAR (HTTP Archive format).
2. Optic is your API version control tool, like git for APIs. "Undocumented" endpoints are like "Untracked" files in git. Add operations one at a time or use optic update openapi.yaml --all to document all of them at once
Prevent breaking changes with API diffs
Breaking changes ruin your API consumer's days. Optic prevents breaking changes from reaching production with its accurate and robust OpenAPI diff. The diff command is built to work with Git workflows, and has full support for OpenAPI 3 & 3.1, $ref, and complex schema types like oneOf/allOf/anyOf.
- optic diff openapi.yaml --base main --check
Verify your API is working-as-designed
With Optic you can verify your API behavior in CI and understand your team's API Test Coverage (the % of your API functionality your testing covered). If optic verify detects no diffs, and you have high API Coverage, you can be very confident your API is working as designed.
- optic verify openapi.yml
Build a consistent API that follows your team's standards
Optic makes it easy for everyone on your team to review API changes, and automate your API standards. It makes API linting usable and productive for developers on teams like Snyk because it raises the quality of the APIs without getting in the way of developers.
You can read about how Optic goes beyond simple API Linting.
Here is an example of a team's automated API standards:
- - breaking-changes # prevent all breaking changes
- - naming: # Naming rules apply on added properties, but won't fail on legacy
- applies: added
- pathComponents: camelCase
- requestHeaders: Capital-Param-Case
- queryParameters: Capital-Param-Case
- - examples: # Examples in the OpenAPI are required and must match the schemas
- require_request_examples: true
- require_response_examples: true
- require_parameter_examples: true
Community & Support
- If you run into bugs, please open Issues.
- Anyone is welcome to book office hours for support or to talk about contributing.
Thanks goes to these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!
OPTIC_TELEMETRY_LEVEL=off - disables telemetry (both usage, and error reporting)
OPTIC_TELEMETRY_LEVEL=error - disables telemetry (only usage data is sent)