Optic

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

Programming language: TypeScript

License: MIT License

Tags: API    

Latest version: v8.5.0

README

Adopt OpenAPI. Start working API-first.

Optic's Open Source tools make OpenAPI and API-first practices easy for any team to adopt.

Installation

npm install -g @useoptic/optic

Diff OpenAPI specifications

Understand the API changes between two versions of an OpenAPI descriptions. Optic helps teams review proposed API changes:

diff current branch with base branch

optic diff openapi.yaml --base main

between two OpenAPI files

optic diff openapi.yaml openapi-changed.yaml

Catch breaking changes

API diffs containing breaking changes will be flagged so you do not break consumers. Optic helps you keep your promises.

optic diff openapi.yaml --base main --check

Read breaking change documentation

Easily adopt OpenAPI

Create new and update existing OpenAPI specifications straight from your services' traffic. Optic makes it easy to adopt OpenAPI in a day, without changing how you work.

Tracking changes with Optic:

Show Optic real API traffic using the oas capture commands. Traffic can come from your development environment, tests, or the browser.

oas capture --proxy localhost:3000 traffic.har

Captured traffic is like working copy in Git. Use oas status to see the difference between how your OpenAPI specification says your API works, and how it actually works.

oas openapi.yaml status --har traffic.har

Run oas add and oas update to update the spec. Optic precision patches your OpenAPI file with the same additions, updates, and removals you would manually write. This is faster and much less error-prone than writing OpenAPI by hand.

oas openapi.yaml add --har traffic.har  GET /lists

oas openapi.yaml update --har traffic.har

A collaborator, not a generator

Using oas to update your spec is like working with a collaborator. It helps you write all the boilerplate OpenAPI and keep your spec in sync with the actual API's behavior.

✅ Never overwrites changes developers make to the same OpenAPI file

✅ Respects $refs across multiple files

✅ Improves accuracy of your specification

✅ Speeds up your team

Read Adopting OpenAPI documentation

Resources

• Documentation
• Beyond API Linting: How Optic is different
• Adding Optic to your CI Pipeline
• Book office hours

License

MIT

Contributors ✨

Thanks goes to these wonderful people (emoji key):

<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->

<!-- ALL-CONTRIBUTORS-BADGE:END --> <!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --> <!-- prettier-ignore-start --> <!-- markdownlint-disable --> 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📖

<!-- markdownlint-restore --> <!-- prettier-ignore-end -->

<!-- ALL-CONTRIBUTORS-LIST:END -->

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