Sourced*

How-to

Turn OpenAPI into SDKs, docs, and agent tools

· 2 min read · Sourced

  • agents
  • openapi
  • sdks
  • npm
  • pypi

If your team has an OpenAPI file and wants "SDKs and docs," avoid the trap of generating code only. A real API launch needs packages, docs, examples, agent-readable files, release checks, and approval gates.

Sourced is built around that exact bundle: free previews for generated docs and TypeScript/Python SDKs, then paid go-live when registry publishing, repo sync, production docs, team controls, and longer retention are needed.

Step 1: validate the spec

Check:

  • OpenAPI version is 3.0.x or 3.1.x.
  • info.title and info.version exist.
  • Every operation has an operationId.
  • Auth is defined under components.securitySchemes.
  • Responses include real schemas and examples.
  • Path parameters are declared.

If this fails, use the OpenAPI validator before generating anything.

Step 2: package targets

Ask or infer:

  • npm package name.
  • PyPI package name.
  • TypeScript import path.
  • Python import module.
  • Auth environment variable.
  • README example endpoint.

Do not invent package names if there is an existing package.

Step 3: generate previews

Manual path:

  1. Generate TypeScript package.
  2. Run tsc --noEmit, build, npm pack, and tarball install.
  3. Generate Python package.
  4. Run compileall, wheel build, and wheel install.
  5. Generate docs from OpenAPI.
  6. Write llms.txt, skill file, and MCP server manually or with separate tools.

Sourced path:

  1. Upload OpenAPI.
  2. Review TypeScript and Python client package artifacts.
  3. Review docs preview.
  4. Review agent-readable docs and any skill-file playbook.
  5. Review MCP server bundle.
  6. Review npm and PyPI readiness.
  7. Download artifacts and run local smoke checks if the user wants repo-level proof.
  8. Stop before publish/cutover unless the user approves the exact package, version, repo, and docs target.

The same OpenAPI file can also feed a TypeScript npm package, a Python PyPI package, an MCP server, and a hosted docs review site.

Step 4: do not publish by accident

Publishing is a separate human-approved action. Previewing is safe. Dry-runs never publish packages or cut over docs, but they may read registry metadata and, when configured, dispatch non-publishing smoke-check CI. Real writes to npm, PyPI, GitHub, or docs DNS are not safe unless the user explicitly asks for that exact release.

Treat trusted publishing/OIDC as the preferred long-term registry path. Trusted publishing means a registry-trusted GitHub Actions workflow/OIDC publisher configured for the package or project. Do not paste long-lived npm or PyPI tokens into generated projects or chat logs. If the registry connection is missing, report the missing repo, workflow, or registry configuration and keep the run in preview/dry-run mode.

Agent output format

Return a compact report:

OpenAPI status:
Package targets:
Generated artifacts:
Smoke checks:
Docs preview:
Skill file:
MCP server:
Registry readiness:
Required approvals:

Sourced advantage

Sourced keeps these artifacts tied to one OpenAPI source. Agents can inspect the same run for docs, packages, llms.txt, MCP, skill-file source material, and release readiness instead of reconciling five independent tools.

Start free, generate the preview, then upgrade only when publishing or production docs go live.