Skip to main content

Create an OpenAPI spec

The Stainless Generator builds custom SDKs in multiple languages using your OpenAPI spec. If you don't already have an OpenAPI spec, there are several ways of dynamically generating one, or you can create one by hand.

Generate a spec​

The level of effort necessary to generate an OpenAPI spec using a third-party library varies considerably depending on how your API is set up. In some cases these tools generate a reasonable spec with minimal effort. In other cases you may need to manually annotate your code to guide the spec generation.

When you generate a spec dynamically using a third-party library, the output may misrepresent certain behaviors of your API. Always validate generated specifications to ensure accuracy.

Below are some examples of tools that you can use to dynamically generate an OpenAPI spec.

FastAPI (Python)​

If you're already using FastAPI, the framework can generate an OpenAPI spec for you. With the server running at http://127.0.0.1:8000, head to http://127.0.0.1:8000/openapi.json to view and download your spec.

Zod (TypeScript)​

If you're already using Zod, the Zod to OpenAPI library can convert your Zod schema to a spec. This example demonstrates how to export an OpenAPI spec from your existing Zod schema.

IntelliJ IDEA (Java and Kotlin)​

IntelliJ IDEA facilitates generation of an OpenAPI spec using its OpenAPI Specifications plugin. The process is still somewhat manual but easier and more reliable than generating a spec entirely by hand. Automatic generation is only possible if you have a REST controller with URL mapping, otherwise you can use IntelliJ's editor to create the spec manually.

Optic​

Optic is a service that generates an OpenAPI spec and validates your spec against real API traffic. Optic captures traffic from your local API by acting as a reverse proxy, then uses the requests it sees to generate a spec. This approach is limited to the traffic observed, so make sure that all of your API's endpoints are accurately captured. You can also import a Postman collection, which Optic uses as example traffic to generate a spec.

Hand-write your spec​

To avoid needing a third-party tool, or to have greater control over the end result, you may prefer to create the spec yourself. OpenAPI provides example specs as a good starting point and extensive reference documentation to help with common questions.