seankeenan-at / optic

Optic makes it easy to document your APIs, prevent breaking changes, and follow an API style-guide

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 ← write your API promises down

🛑 Prevent breaking changes from shipping ← keep your promises

✅ Verify your API is working-as-designed (the OpenAPI and implementation are in sync) ← make sure the API works as-designed

🎨 Build a consistent API that follows your team's 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 oas capture https://api.github.com OR provide a HAR (HTTP Archive format).
2. Then run optic oas verify to see a list of "Undocumented" endpoints. Optic is your API version control tool, like git for APIs. "Undocumented" endpoints are like "Untracked" files in git.
3. Add operations one at a time or use --document all to document all of them at once

Documentation: Generate an OpenAPI from traffic

document-for-web.mp4

Read Documentation

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

Documentation: Diff OpenAPI and Catch Breaking Changes

diff-openapi.mp4

Read Documentation

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 oas verify detects no diffs, and you have high API Coverage, you can be very confident your API is working as designed.

optic oas verify openapi.yml

Documentation: Verify your API works as designed

verify-api-behavior.mp4

Read Documentation

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:

ruleset:
  - 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    

api-review.mp4

Read Documentation

---

Community & Support

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

License

MIT

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Aidan Cunniffe 📖 💻	devdoshi 📖 💻	Evan Mallory 📖	Jaap van Hardeveld 💻 📖	Ronak Shah 💻 📖	taraedits 📖	Lou Manglass 💻 📖
Nate Meyer 💻	Tim Gates 📖	Matthew Hudson 📖	LaV 📖	Gaurav Nelson 📖	Ross Nordstrom 🎨 💻 🐛	Kin Lane 🤔 🖋
Viljami Kuosmanen 🤔 🖋	Richard Crowley 🔬 🤔	dnmtr 👀	Tim Perry 💻	jordaniza 📖	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 📖	Mukesh 💻	Tony Knight 📖	Roger Dickey, Jr 📖

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

Telemetry

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)