How to Generate Openapi

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.yml

Other Approaches

Generate from CodeGenerate 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 OpenAPIYour code types will always match your spec. Great for design-first workflowsImpossible 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 GatewayThe traffic in your gateway generates accurate OpenAPI specificationsMust 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 DSLsMake OpenAPI easier to write with a design-first workflowLock-in to smaller / newer projects.Typespec (opens in a new tab), Fern (opens in a new tab)