extract-openapi-from-code

Use when extracting or generating an OpenAPI spec from existing API code. Triggers on "extract OpenAPI", "code first", "generate spec from code", "FastAPI OpenAPI", "Spring Boot OpenAPI", "NestJS swagger", "Django OpenAPI", "Flask OpenAPI", "Rails swagger", "Laravel OpenAPI", "existing API code"

Ir para a instalação

Repositório: speakeasy-api/skills
Última atividade na origem: 3 de fevereiro de 2026 às 18:15
Idioma detectado do SKILL.md: inglês
Estrelas: 18
Forks: 6

Opções de instalação

Por padrão, está selecionado o prompt que primeiro revisa a origem. Você pode mudar para um comando direto ou baixar uma cópia local.

Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.

Um comando direto ignora o prompt de revisão. Verifique a origem antes de executá-lo.

npx skills add https://github.com/speakeasy-api/skills --skill extract-openapi-from-code

O comando permanece em uma só linha. Role horizontalmente para revisá-lo antes de copiar.

Prefere uma cópia local? Baixe os arquivos disponíveis atualmente no SkillsMP.

Revise os arquivos de origem

Leia o SKILL.md e os arquivos complementares exibidos pelo SkillsMP antes de decidir se vai instalar.

Explorador de arquivos

9 arquivos

SKILL.md

Instruções da origem · Visualização somente leitura

Voltar à pesquisa Voltar à instalação

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

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

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

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

flask openapi write openapi.json

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

python manage.py spectacular --file openapi.yaml

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

# 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

# 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

// 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();

// 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));

npx tsx scripts/export-openapi.ts

rails rswag:specs:swaggerize

php artisan l5-swagger:generate

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

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

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

# 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"

@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(): ...

# 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']
        }
    }
}

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

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

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

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

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`

extract-openapi-from-code

Opções de instalação

Revise os arquivos de origem