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.

Content Guides

Each guide provides detailed setup, schema definition, Speakeasy extensions, authentication, and troubleshooting for that framework.

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"

Adding Speakeasy Extensions

After extracting a spec, add Speakeasy-specific extensions for better SDK output. These can be added in framework config or via overlay.

FastAPI: Add Extensions via openapi_extra

@app.get(
    "/items",
    openapi_extra={
        "x-speakeasy-retries": {
            "strategy": "backoff",
            "backoff": {"initialInterval": 500, "maxInterval": 60000, "exponent": 1.5},
            "statusCodes": ["5XX", "429"]
        },
        "x-speakeasy-group": "items",
        "x-speakeasy-name-override": "list"
    }
)
def list_items(): ...

Django: Add Extensions via SPECTACULAR_SETTINGS

# settings.py
SPECTACULAR_SETTINGS = {
    # ... other settings
    'EXTENSIONS_TO_SCHEMA_FUNCTION': lambda generator, request, public: {
        'x-speakeasy-retries': {
            'strategy': 'backoff',
            'backoff': {'initialInterval': 500, 'maxInterval': 60000, 'exponent': 1.5},
            'statusCodes': ['5XX']
        }
    }
}

Spring Boot: Add Extensions via Custom OperationCustomizer

@Bean
public OperationCustomizer operationCustomizer() {
    return (operation, handlerMethod) -> {
        operation.addExtension("x-speakeasy-group",
            handlerMethod.getBeanType().getSimpleName().replace("Controller", "").toLowerCase());
        return operation;
    };
}

NestJS: Add Extensions via Decorator Options

@Get()
@ApiOperation({
  summary: 'List items',
  operationId: 'listItems'
})
@ApiExtension('x-speakeasy-group', 'items')
@ApiExtension('x-speakeasy-name-override', 'list')
listItems() { ... }

Via Overlay (Any Framework)

If you cannot modify framework code, use an overlay:

overlay: 1.0.0
info:
  title: Speakeasy Extensions
  version: 1.0.0
actions:
  - target: $.paths['/items'].get
    update:
      x-speakeasy-group: items
      x-speakeasy-name-override: list

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

Related Skills

• manage-openapi-overlays - Add x-speakeasy-* extensions via overlay
• start-new-sdk-project - Generate SDK after extraction