OpenParable
Skip to content
← Back to skills

Openapi

Development
openapi

Openapi is an Agent Skill for development published in the flexprice/flexprice repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Swagger + Speakeasy SDK/MCP pipeline (make swagger, sdk-all), api/custom merge. Trigger: openapi, swagger, sdk-all, MCP.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/flexprice/flexprice/blob/HEAD/.cursor/skills/openapi/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/openapi, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

openapi — OpenAPI & SDKs

Source of truth

  • Handlers: Swagger comments in internal/api/**.
  • Generated specs: docs/swagger/ (run generation — do not hand-edit JSON as primary source).

Standard sequence

After route or Swagger annotation changes:

make swagger
make sdk-all

make sdk-all (per AGENTS.md) validates, generates SDKs/MCP, merges api/custom/**.

OpenAPI-only validation:

make speakeasy-validate

Custom vs generated

  • Do not put long-lived custom logic only in generated trees under api/go, api/typescript, api/python, api/mcp.
  • Put custom code in api/custom/<lang>/ and rely on make merge-custom (often part of sdk-all).

MCP tooling

Filtered spec and allowed tags live under .speakeasy/mcp/ — changing exposed tools requires config update + regenerate flow documented in AGENTS.md.

When to skip full sdk-all

Small internal-only HTTP tweak with no exported contract change: make swagger alone may suffice; coordinate with reviewers if public SDK repos are consumers.

Related

  • Tests after API change: expand handler tests or api/tests if behavior is user-facing SDK contract.