extract-openapi-from-code Skill

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

Agent Skills: extract-openapi-from-code

Install this agent skill to your local

Skill Files