extract-openapi-from-code

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

Framework	Language	Guide
FastAPI	Python	content/frameworks/fastapi.md
Flask	Python	content/frameworks/flask.md
Django REST Framework	Python	content/frameworks/django.md
Spring Boot	Java	content/frameworks/spring-boot.md
NestJS	TypeScript	content/frameworks/nestjs.md
Hono	TypeScript	content/frameworks/hono.md
Rails	Ruby	content/frameworks/rails.md
Laravel	PHP	content/frameworks/laravel.md

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

Input	Required	Description
Framework	Yes	The API framework in use (see Decision Framework)
Project path	Yes	Root directory of the API project
Output path	No	Where to write the spec (default: openapi.json or openapi.yaml)
Target language	No	SDK target language, if generating an SDK after extraction

Outputs

Output	Description
OpenAPI spec	A JSON or YAML file describing the API
Validation report	Lint results from speakeasy lint

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:

Framework	Language	Method	Requires Running Server?
FastAPI	Python	Built-in export	No
Flask (flask-smorest)	Python	CLI command	No
Django REST Framework	Python	drf-spectacular CLI	No
Spring Boot (springdoc)	Java	HTTP endpoint	Yes
NestJS	TypeScript	HTTP endpoint or script	Yes
Hono (zod-openapi)	TypeScript	Programmatic export	No
Rails (rswag)	Ruby	Rake task	No
Laravel (l5-swagger)	PHP	Artisan command	No

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

Issue	Symptom	Fix
Missing operationIds	Lint warning; SDK methods get generic names	Add operationIds via overlay or use speakeasy suggest operation-ids -s openapi.json
Missing descriptions	Lint hints; SDK has no documentation	Add descriptions to endpoints and schemas in source code or via overlay
Overly permissive schemas	Schemas use additionalProperties: true or lack type constraints	Tighten schemas in source code; use stricter validation decorators
No response schemas	Lint errors; SDK return types are any/object	Add explicit response models to your framework endpoints
Duplicate operationIds	Lint errors; generation fails	Ensure each endpoint has a unique operationId
Missing authentication	No security schemes in spec	Add security metadata to your framework config or via overlay

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

Error	Cause	Solution
ModuleNotFoundError (Python)	App dependencies not installed	Run pip install -r requirements.txt or pip install -e .
Connection refused (Spring Boot, NestJS)	Server not fully started	Increase sleep time or poll for readiness
Empty or minimal spec	Routes not registered at import time	Ensure all route modules are imported; check lazy loading
YAML parse error	Extracted file has invalid syntax	Re-extract; check for print statements polluting stdout
Cannot find module (Node.js)	Dependencies not installed	Run npm install or yarn install
No /v3/api-docs endpoint (Spring Boot)	springdoc not configured	Add springdoc-openapi-starter-webmvc-ui to dependencies
No /api-json endpoint (NestJS)	Swagger module not set up	Configure SwaggerModule.setup(app, ...) in main.ts

Related Skills

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