Document an existing service with OpenAPI
An API specification documents all the promises you have made to your consumers. You can't keep those promises (prevent breaking changes) until you write those promises down. That's why the first step to shipping better APIs is to accurately document what you already have built. Writing OpenAPI by hand is tedious and error-prone -- here is an overview of better options.
API Snapshot Testing
Optic uses OpenAPI a snapshot of your API behavior. When you run your test suite with Optic, it generates accurate OpenAPI descriptions for every endpoint your tests cover. You can run it over and over again, updating your OpenAPI specification whenever your API behavior changes. This approach works great for existing APIs, but only if you have decent test coverage -- if not, you should consider some of the other approaches we have below.
Guide: Generate OpenAPI from Traffic
Demo: Set up a demo call
optic capture openapi.ymlOther Approaches
| Advantages | Limitations | Guides | |
|---|---|---|---|
| Generate from Code | Generate an accurate OpenAPI spec from the types in your code. | Quality varies from framework to framework. May require code changes to get reasonable output. Manual changes to specs will be overwritten. | Express, Go Gin, Spring Boot, Ruby, Fastify |
| Generate Code from OpenAPI | Your code types will always match your spec. Great for design-first workflows | Impossible to do this for existing projects. The off-the-shelf tools may not work for you or follow your style. | OpenAPI Generator (opens in a new tab) |
| Generate from Gateway | The traffic in your gateway generates accurate OpenAPI specifications | Must be using Cloudflare (other offerings don't work). Not a part of developer workflow so governance is difficult. | Cloudflare API Discovery (opens in a new tab) |
| OpenAPI DSLs | Make OpenAPI easier to write with a design-first workflow | Lock-in to smaller / newer projects. | Typespec (opens in a new tab), Fern (opens in a new tab) |