home / skills / feiwanghub / playground / openapi-spec-generation-skill

openapi-spec-generation-skill skill

safe

/skills/.trae/skills/openapi-spec-generation-skill

This skill generates OpenAPI 3.0 YAML from simple JSON definitions, scaffolding endpoints and responses to accelerate API documentation.

npx playbooks add skill feiwanghub/playground --skill openapi-spec-generation-skill

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

824 B

---
name: openapi-spec-generation-skill
description: "Generate OpenAPI 3.0 YAML specifications from simple JSON definitions."
---

# OpenAPI Spec Generation Skill

This skill allows you to quickly scaffold OpenAPI 3.0 documentation by providing a simple JSON definition of your API structure.

## Capabilities

- Convert simplified JSON path definitions to valid OpenAPI 3.0 YAML.
- Automatically scaffolds standard response structures.

## Usage

1. Create a `api_def.json` file:

```json
{
  "title": "My API",
  "version": "1.0.0",
  "paths": [
    {"path": "/users", "method": "get", "summary": "List users"},
    {"path": "/users", "method": "post", "summary": "Create user"}
  ]
}
```

2. Run the generator:

```bash
python3 .shared/openapi-spec-generation-skill/scripts/generate_spec.py api_def.json openapi.yaml
```

Overview

This skill generates OpenAPI 3.0 YAML specifications from a minimal JSON description of your API. It scaffolds paths, methods, and basic responses so you can get a valid OpenAPI document quickly. The output is ready for documentation tools, code generation, or API gateways.

How this skill works

You provide a simplified JSON that lists API metadata and an array of path entries (path, method, summary, and optional parameters or responses). The generator converts each entry into OpenAPI 3.0 YAML, adding standard response placeholders and top-level info (title, version). It emits a complete YAML file that conforms to OpenAPI structure and is suitable for further refinement or automated tooling.

When to use it

You need a quick, initial OpenAPI spec for an existing API or prototype.
You want to convert team-maintained simple JSON route definitions into a usable spec.
You want to generate a baseline spec before adding detailed schemas and examples.
You are preparing documentation, client SDKs, or API gateway configs from minimal input.

Best practices

Include clear summaries and operationIds in the JSON to produce meaningful OpenAPI operations.
Add parameters and response schemas in the input JSON when possible to reduce manual edits later.
Validate the generated YAML with an OpenAPI linter or validator before publishing.
Iterate: use the scaffolded YAML as a living document and enrich schemas, examples, and security sections.

Example use cases

Scaffold an initial OpenAPI file for a microservice to share with frontend developers.
Convert router definitions from a simple JSON manifest into a spec for client SDK generation.
Rapidly create docs for a prototype API to demo endpoints and expected responses.
Generate base specs to feed into CI checks that ensure routes are documented.

FAQ

What input does the generator expect?

A minimal JSON with title, version, and a list of paths each including path, method, and summary; optional fields can extend parameters and responses.

Is the output ready for production?

The generated YAML is a valid OpenAPI 3.0 scaffold, but you should add detailed schemas, examples, and security definitions before using it in production.