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

  1. ```bash
  2. npm install -g @useoptic/optic
  3. ```

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.

  1. ```bash
  2. optic diff openapi.yaml --base main --check
  3. ```


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.

  1. ```bash
  2. optic verify openapi.yml
  3. ```


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:
  1. ```yaml
  2. ruleset:
  3.   - breaking-changes # prevent all breaking changes
  4.   - naming:  # Naming rules apply on added properties, but won't fail on legacy
  5.       applies: added
  6.       pathComponents: camelCase
  7.       requestHeaders: Capital-Param-Case
  8.       queryParameters: Capital-Param-Case
  9.   - examples: # Examples in the OpenAPI are required and must match the schemas
  10.       require_request_examples: true
  11.       require_response_examples: true
  12.       require_parameter_examples: true    
  13. ```


Community & Support

- If you run into bugs, please open Issues.
- Anyone is welcome to book office hours for support or to talk about contributing.



Contributors ✨

Thanks goes to these wonderful people (emoji key):

All Contributors

Aidan Cunniffe

📖 💻


📖 💻

Evan Mallory


Jaap van Hardeveld

💻 📖

Ronak Shah

💻 📖



Lou Manglass

💻 📖

Nate Meyer


Tim Gates


Matthew Hudson




Gaurav Nelson


Ross Nordstrom

🎨 💻 🐛

Kin Lane

🤔 🖋

Viljami Kuosmanen

🤔 🖋

Richard Crowley

🔬 🤔



Tim Perry




Sandy Vanderbleek


Dave Rolsky


Baptiste Darthenay


Alex Miller


Joseph Shearer


Ray Bejjani


Adrien Brault


Nicholas Lim

📖 💻

Stephen Mizell

💻 📖

Bojan Đurđević


Taras Mankovski


Ikko Ashimine




Tony Knight


Roger Dickey, Jr


This project follows the all-contributors specification. Contributions of any kind welcome!


Optic collects telemetry which is used to help understand how to improve the product. For example, this usage data helps to debug issues and to prioritize features and improvements based on usage. The usage of our telemetry data falls under our privacy policy. While this information does help us build a great product, we understand that not everyone wants to share their usage data. If you would like to disable telemetry you can add an environment variable that will opt out of sending usage data:

OPTIC_TELEMETRY_LEVEL=off - disables telemetry (both usage, and error reporting)
OPTIC_TELEMETRY_LEVEL=error - disables telemetry (only usage data is sent)