Use a local OpenAPI spec

Generate your API and SDK documentation based on a local OpenAPI spec and Stainless config to see unpublished changes or experiment in an isolated environment.

This approach will only work for local development.

First, create a new test-specs directory in the root of the local copy of your docs project. The test-specs directory is ignored in our default .gitignore, and should not be committed.

Next, put the OpenAPI spec and Stainless config you want to use in the test-specs directory. If you want to start with your current versions, copy them from the Stainless dashboard.

📁 <root>
├─ 📁 public/
├─ 📁 src/
│  ├─ 📁 assets/
│  └─ 📁 content/
│     └─ 📁 docs/
├─ 📁 test-specs/
│  ├─ 📄 openapi.json
│  └─ 📄 openapi.stainless.yml
├─ 📄 .env
├─ 📄 astro.config.ts
└─ 📄 package.json

Update your .env file to include the paths to your local specs. If you used the Stainless CLI to authenticate and don’t have an .env file, create one with the content shown below.

.env

STAINLESS_CONFIG_PATH=./test-specs/openapi.stainless.yml
OPENAPI_PATH=./test-specs/openapi.json

Your local development server will now use the files specified in your environment variables.