Skip to main content

Building a “copilot” that helps teams adopt OpenAPI

· 3 min read

What if it were easy for every team building an API to adopt OpenAPI? Overnight, most APIs would have some basic documentation, there would be fewer breaking changes, and quality of APIs would improve as more teams started working API-first.

Many open source projects and commercial tools have made it possible to generate OpenAPI from your code or by analyzing API traffic. But using generated OpenAPI in your workflow is difficult. Manual fixes/changes to schemas will be overwritten, and working design-first is not possible. Could we get the power of an OpenAPI generator without these downsides?

OpenAPI generators → OpenAPI Copilot

GitHub Copilot has shown how productive it can be to combine human judgement with very smart in-line generators. Developers are not handing over control to Copilot, they still make all the decisions, then copilot gets them through the boilerplate faster.

There has been a lot of open source work in the Optic repo exploring a similar approach. Instead of a generator that overwrites the OpenAPI description every time you run it, imagine one that made small, surgical patches to the OpenAPI file. You can collaborate with a generator like that — allowing it to tackle all the boilerplate, and improve the accuracy of your spec — all without giving up flexibility or control.

The “smarts” behind the patches come from observing API traffic and diffing that traffic against your OpenAPI description. Real traffic allows Optic to be aware of all the next changes a developer might make to the OpenAPI file.

  • Just added some new API operations? Optic sees them and knows you might want to document them
  • Add new properties to your response, or change types? Optic sees the diff and is ready to help you update the schema
  • recently added status codes or bodies? Optic sees them and knows you might want to document them.

How it works

  1. Capture traffic as a HAR file - we have a few options + suggestions for how to do this. It’s definitely the hardest part and we’re working on some more magic here to make it automatic.
  2. Run oas openapi.yml status to review diffs:
  1. Want to document a new API operation? Run oas openapi.yml add:
  1. Want to update an existing API operation to reflect its actual behavior? Run oas openapi.yml update

The add and update commands both write to the file system, so make sure your OpenAPI file is tracked by git so you can revert changes easily. Here’s a video demo where Optic updates an OpenAPI file that uses $ref — it does not break the references and works across multiple files which is super helpful for large specifications!

Watch a video demo:

Try it yourself: Get started docs

Project Status: the tool is early and has some known limitations. It will not diff or patch query parameters, headers, or security schemas, but it also will not mess with any you document them manually. We’re interested in supporting more of OpenAPI and making capture traffic a lot easier. If you have ideas or want to get involved come chat on GitHub discussion.

What’s next?

Adopting OpenAPI is the first step towards working API-first. Optic can help you on the rest of your journey.