Skip to content
develop
Switch branches/tags
Code

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
 
 
 
 
 
 
bin
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Announcement: Interested in more advanced team workflows? An easier way to run Optic in real environments? Check out Optic Cloud, now in Beta.


Optic

Optic uses real traffic to document and test your APIs

Build Status issues rust closedprs currentversion License stars

  • Language agnostic, works with any Rest API
  • Optic observes development traffic and learns your API's behavior
  • Optic detects API changes by diffing traffic against the current specification
  • Optic adds an accurate API changelog to every Pull Request

Try OpticDocument APIsDetect ChangesOptic GitBotContributing License

Check out our Live Demo of GitHub's API

Try Optic

Similar to git init

Install Optic with npm or yarn"

yarn global add @useoptic/cli
npm install @useoptic/cli -g

Then run init command:

## Navigate to your API project directory
api init

Set up aliases for the commands your team runs when building the API in optic.yml

ie npm start -> api start

ie newman run mycollection.json -> api run postman-tests

name: My API
tasks:
  start:
    command: npm start
    inboundUrl: http://localhost:4000
  postman-tests:
    command: newman run mycollection.json
    useTask: start

How does Optic monitor local traffic? Whenever you start your API or run tests using Optic's CLI, it will observe your traffic and surface API diffs. All of this processing is done locally, in the background, by a Rust binary built from the open source code in this repository.

Document your API using real traffic

Similar to git add

Once you add Optic to your API, hit it with some traffic, and document your first endpoints.

You just have to provide Optic with your API paths, and it will document every status code, response body, and request body automatically based on its observations.

You don't have to worry about hitting every possible request/response your first go -- Optic isn't "one-shot", it builds your spec up incrementally as it makes more observations about your API's behavior. For example, if Optic sees a 200 for an endpoint, and later sees a 400 for the same endpoint, it will help you add the new response.

api start
[optic] Starting My API API on Port: 3005, with npm run server-start

The api documentation

Detect API Changes

Similar to git status

While you develop your API and run tests locally, Optic diffs the traffic to find new endpoints, or changes to existing endpoints. These API diffs are listed when you run api status:

Optic

Use the Optic UI to Review Diffs + Update your Specification

Similar to staging changes

When Optic detects an API diff, it helps you:

  • Document new endpoints without writing a bunch of OpenAPI
  • Update your API specification with a few clicks
  • Detect any unplanned changes, breaks and regressions, then fix them

bigdiff

An API Changelog in Every PR

Similar to GitHub's compare page, but for API changes

The Optic GitBot adds an API Changelog during Code Review, so your team understands how the API will change when each PR is merged.

🚦 Prevent Breaking Changes

Discover breaking changes before they're merged. Request compatible changes in code review, or coordinate the breaking changes with consumers.

🔎 API First

Adding explicit API changelogs in PRs facilitates discussion and leads to better API design. It's also a great way to make sure unintended API changes don't get deployed.

Updated Docs

No more doc drift. When you approve an API change Optic also updates the specification.

Install & Set up the GitBot

changelog


Documentation https://useoptic.com/docs

Resources

Want to help us design the next features? Book Maintainer Office Hours

License

MIT

Contributors

Thanks goes to these wonderful people (emoji key):

All Contributors


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!