extract-openapi-from-code

Extract an OpenAPI specification from an existing API codebase. Covers eight major frameworks across Python, Java, JavaScript/TypeScript, Ruby, and PHP.

When to Use

• User has an existing API and wants to generate an OpenAPI spec from it
• User wants to create an SDK from code that has no OpenAPI spec yet
• User mentions a specific framework (FastAPI, Flask, Django, Spring Boot, NestJS, Hono, Rails, Laravel)
• User says: “extract OpenAPI”, “code first”, “generate spec from code”, “existing API code”

Inputs

Outputs

Prerequisites

• The API project must be buildable and its dependencies installed
• For runtime extraction (FastAPI, Spring Boot, NestJS, Hono), the app must be importable or startable
• speakeasy CLI installed for post-extraction validation and SDK generation

Decision Framework

Use this tree to determine the extraction method:

Command

Choose the command matching your framework below. After extraction, always validate with speakeasy lint.

Python: FastAPI

FastAPI generates an OpenAPI schema at runtime. Export it without starting the server:

python -c "import json; from myapp import app; print(json.dumps(app.openapi()))" > openapi.json

Replace myapp with the module containing your FastAPI app instance. If the app uses a factory pattern:

python -c "import json; from myapp import create_app; app = create_app(); print(json.dumps(app.openapi()))" > openapi.json

You can also start the server and fetch from http://localhost:8000/openapi.json.

Python: Flask (flask-smorest)

Requires flask-smorest or apispec:

flask openapi write openapi.json

If using apispec directly, export programmatically:

import json
from myapp import create_app, spec
app = create_app()
with app.app_context():
    print(json.dumps(spec.to_dict()))

Python: Django REST Framework

Requires drf-spectacular:

python manage.py spectacular --file openapi.yaml

For JSON output:

python manage.py spectacular --format openapi-json --file openapi.json

Java: Spring Boot

Requires springdoc-openapi. Start the application, then fetch the spec:

# Start the app (background)
./mvnw spring-boot:run &
# Wait for startup
sleep 15

# Fetch the spec
curl http://localhost:8080/v3/api-docs -o openapi.json

# For YAML format
curl http://localhost:8080/v3/api-docs.yaml -o openapi.yaml

# Stop the app
kill %1

If the server runs on a different port or context path, adjust the URL accordingly.

TypeScript: NestJS

Requires @nestjs/swagger. Start the application, then fetch:

# Start the app (background)
npm run start &
sleep 10

# Fetch the spec (default path with SwaggerModule)
curl http://localhost:3000/api-json -o openapi.json

# Stop the app
kill %1

Alternatively, create a script to export without running the server:

// scripts/export-openapi.ts
import { NestFactory } from '@nestjs/core';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
import { AppModule } from '../src/app.module';
import * as fs from 'fs';

async function bootstrap() {
  const app = await NestFactory.create(AppModule, { logger: false });
  const config = new DocumentBuilder().setTitle('API').build();
  const doc = SwaggerModule.createDocument(app, config);
  fs.writeFileSync('openapi.json', JSON.stringify(doc, null, 2));
  await app.close();
}
bootstrap();

TypeScript: Hono (zod-openapi)

Requires @hono/zod-openapi. Export the schema programmatically:

// scripts/export-openapi.ts
import { app } from '../src/app';
import * as fs from 'fs';

const doc = app.doc('/doc', {
  openapi: '3.1.0',
  info: { title: 'API', version: '1.0.0' },
});
fs.writeFileSync('openapi.json', JSON.stringify(doc, null, 2));

Run with:

npx tsx scripts/export-openapi.ts

Ruby: Rails (rswag)

Requires rswag:

rails rswag:specs:swaggerize

The spec is written to swagger/v1/swagger.yaml by default (configurable in config/initializers/rswag_api.rb).

PHP: Laravel (l5-swagger)

Requires l5-swagger:

php artisan l5-swagger:generate

The spec is written to storage/api-docs/api-docs.json by default.

Post-Extraction Steps

After extracting the spec, always run these steps:

1. Validate the spec

speakeasy lint openapi --non-interactive -s openapi.json

2. Fix issues with overlays (if needed)

If validation reveals issues, use an overlay rather than modifying the extracted spec directly:

speakeasy overlay apply -s openapi.json -o fixes.yaml

To fix validation errors, create an OpenAPI overlay file and apply it with speakeasy overlay apply -s <spec> -o <overlay>.

3. Generate an SDK

speakeasy quickstart --skip-interactive --output console \
  -s openapi.json \
  -t <target> \
  -n <name> \
  -p <package>

Run speakeasy quickstart -s <spec> -t <language> to initialize a new SDK project.

Example

Full workflow for a FastAPI project:

# 1. Extract the OpenAPI spec
cd /path/to/my-fastapi-project
python -c "import json; from main import app; print(json.dumps(app.openapi()))" > openapi.json

# 2. Validate
speakeasy lint openapi --non-interactive -s openapi.json

# 3. Generate a TypeScript SDK
speakeasy quickstart --skip-interactive --output console \
  -s openapi.json \
  -t typescript \
  -n "MyApiSDK" \
  -p "my-api-sdk"

Common Issues After Extraction

What NOT to Do

• Do NOT hand-write an OpenAPI spec when the framework can generate one — always extract first
• Do NOT edit the extracted spec directly — use overlays for fixes so re-extraction does not lose changes
• Do NOT skip validation — extracted specs often have issues that block SDK generation
• Do NOT assume the extracted spec is complete — frameworks may omit auth, error responses, or headers
• Do NOT start the server in production mode for extraction — use development or test configuration

Troubleshooting