openapi-r1quest-generator

name	openapi-r1quest-generator
description	Generate ntee-r1quest request projects from Swagger/OpenAPI v3 YAML or JSON files. Use when asked to scan an OpenAPI spec and create .ntd data files plus .nts request files organized by project, HTTP method, and operation name.
argument-hint	<openapi-file> <output-dir> <project-name>

OpenAPI R1Quest Generator

Use this skill to convert a Swagger/OpenAPI v3 spec into an ntee-r1quest request project.

Inputs

Ask for any missing required input:

• OpenAPI spec path, usually .yaml, .yml, or .json
• Output directory
• Project name

Optional input:

• Environment variable names for auth tokens
• Which server URL to use when the OpenAPI spec has multiple servers
• Whether to include example request bodies when schemas/examples are available

Output Layout

Generate one project directory under the requested output directory:

<output-dir>/<project-name>/
  data/
    common.ntd
    auth.ntd
    <operation-name>.ntd
  get-property.nts
  create-property.nts
  update-property.nts
  delete-property.nts

Rules:

• Put shared values in data/common.ntd.
• Put auth-related values in data/auth.ntd when auth exists.
• Put operation-specific body/query/header examples in data/<operation-name>.ntd when the operation needs reusable data.
• Put duplicated Swagger/OpenAPI path, query, header, and cookie parameters in .ntd files and reference them with @i(...) from every generated .nts that uses them.
• Put .nts request files directly under <project-name>/.
• Name request files as <method>-<operation-name>.nts.
• Normalize operation names to lowercase kebab-case.
• Prefer operationId for operation names.
• If operationId is missing, derive the name from HTTP method plus path.

Example:

property-api/
  data/
    common.ntd
    auth.ntd
    create-property.ntd
  get-property.nts
  create-property.nts

Read And Normalize The OpenAPI Spec

Parse the OpenAPI file with a structured parser. Do not parse YAML with ad hoc string splitting.

Extract:

• servers
• paths
• path-level parameters
• operation-level parameters
• reusable components.parameters and Swagger v2 global parameters
• reusable components.schemas, components.requestBodies, components.headers, components.securitySchemes, and Swagger v2 definitions, parameters, responses, and securityDefinitions
• request headers
• request bodies
• security requirements
• response content types when useful for accept

Use the first servers[0].url by default unless the user requested another server.

If the server URL contains variables, create values in data/common.ntd and document the selected defaults.

Respect reusable OpenAPI/Swagger definitions. When a request references a shared parameter, schema, request body, header, response, or security definition, follow the reference and generate request data from the resolved definition instead of flattening or dropping it.

Reuse Shared Data

Prefer .ntd keys for duplicated values instead of repeating literals across .nts files.

Deduplicate at these levels:

• Shared host, base paths, content types, accept headers, auth values, common headers, and API key names -> data/common.ntd or data/auth.ntd.
• Path-level parameters used by multiple methods under the same path -> a shared .ntd file for that path or data/common.ntd when broadly reused.
• Referenced components.parameters or Swagger v2 global parameters used by multiple operations -> one .ntd key with a stable kebab-case name.
• Repeated query parameters across list/search operations -> shared .ntd keys such as page, limit, sort, and filter.
• Reused request body schemas or examples -> one .ntd object reused by each matching .nts.

When a parameter appears in multiple operations with the same meaning, generate one key and reference it from every request:

tenant-id: tenant-123
page: 1
limit: 20

url "@i(host)/tenants/@i(tenant-id)/properties?page=@i(page)&limit=@i(limit)"

Only create operation-specific .ntd keys when the value is truly unique to that operation or when sharing it would make the data file unclear.

Generate .ntd Files

.ntd files store reusable data for @i(...) macros.

Always quote URLs because // starts comments:

host: "https://api.example.com"
content-type: application/json
accept: application/json

For auth tokens, prefer environment macros:

token: @env(API_TOKEN)

For path/query/body examples, generate realistic placeholder data from OpenAPI examples, defaults, enums, schema types, and property names.

For duplicated parameters, use one key per conceptual value. Prefer names from the original parameter name, normalized to kebab-case:

property-id: property-123
tenant-id: tenant-123
x-request-id: request-123

If two parameters normalize to the same key but have different locations or meanings, prefix them with context such as query-, header-, or the operation group name.

Example:

property-id: property-123
page: 1
limit: 20
property: {
  name: "Example property"
  enabled: true
}

.ntd constraints:

• Use @env(KEY) only in .ntd files.
• Do not use @i(...) in .ntd files.
• Do not use @f(...) in .ntd files.
• Quote strings containing ://, //, commas, brackets, or braces.

Generate .nts Files

Each .nts file declares one HTTP request.

Basic shape:

ref ./data/common.ntd

url "@i(host)/properties/@i(property-id)"
type get

header accept, @i(accept)

With auth:

ref ./data/common.ntd
ref ./data/auth.ntd

url "@i(host)/properties"
type get

header accept, @i(accept)
auth bearer @i(token)

With JSON body:

ref ./data/common.ntd
ref ./data/auth.ntd
ref ./data/create-property.ntd

url "@i(host)/properties"
type post

header accept, @i(accept)
header content-type, @i(content-type or "application/json")
auth bearer @i(token)

body @i(property)

With multipart file upload:

ref ./data/common.ntd
ref ./data/auth.ntd

url "@i(host)/files"
type post

header content-type, multipart/form-data
auth bearer @i(token)

body {
  file: @f(./files/example.txt)
}

.nts constraints:

• Put ref statements before other statements.
• Resolve ref paths relative to the .nts file.
• Use quoted strings for url.
• Use @i(...) for host, path parameters, query parameter values, header values, auth values, and body values.
• Use @f(...) only inside body values.
• Do not use @f(...) in headers or auth.
• Every request that sends a body MUST emit a content-type header. Source the value from a referenced .ntd key (@i(content-type)), the exact media type read from the OpenAPI spec, or the or default form @i(content-type or "application/json"). See "Headers And Content Types".

URL And Parameters

Convert OpenAPI path templates:

/properties/{propertyId}

to:

url "@i(host)/properties/@i(property-id)"

For query parameters, include them in the URL:

url "@i(host)/properties?page=@i(page)&limit=@i(limit)"

Put corresponding values in an .ntd file:

page: 1
limit: 20

For OpenAPI path-level parameters, generate the parameter value once and reuse it for every operation under that path unless an operation explicitly overrides the parameter definition.

For operation-level parameters, first check whether the same parameter name, location, schema, and example/default already exists in another operation. If it does, reuse the same .ntd key.

Headers And Content Types

Choose accept from response content types. Prefer application/json when available.

Always emit content-type for requests with a body

Every generated .nts that sends a body MUST include a content-type header. The runtime dispatches on content-type, and a request with a missing or unsupported content-type fails before sending.

Resolve the value in this order:

1. Reference a shared .ntd key. When the same content type is used across operations, define it once and reference it. This is the preferred form:

   content-type: application/json
   

   header content-type, @i(content-type)
   

2. Read the exact content type from the OpenAPI spec. When an operation declares a specific request body media type that differs from the shared value, write that literal media type into the operation's .ntd key (or inline) so the header matches the spec exactly:

   content-type: application/vnd.api+json
   

3. Use the or default fallback. When no .ntd key is guaranteed to be referenced, fall back to a literal default so the request still compiles:

   header content-type, @i(content-type or "application/json")
   

   The default must be an immediate quoted string. Pick it from the operation's declared request media type, preferring:

   1. application/json
   2. multipart/form-data
   3. the first available OpenAPI request content type

Do not emit a content-type header for requests with no body (e.g. plain get or delete) unless the spec explicitly requires one.

For JSON bodies:

header content-type, @i(content-type or "application/json")

For multipart bodies:

header content-type, @i(content-type or "multipart/form-data")

Auth Mapping

Map OpenAPI security schemes:

• HTTP bearer -> auth bearer @i(token)
• HTTP basic -> auth basic @i(credentials)
• API key header -> header <name>, @i(api-key)
• API key query -> append ?<name>=@i(api-key) or &<name>=@i(api-key)

Generate data/auth.ntd with environment macros:

token: @env(API_TOKEN)
api-key: @env(API_KEY)
credentials: @env(API_BASIC_CREDENTIALS)

Use clear environment variable names derived from the project name and security scheme when possible.

Operation Naming

Normalize names:

• getProperty -> get-property
• Create Property -> create-property
• GET /properties/{propertyId} -> get-property-by-property-id

Avoid duplicate file names. If two operations normalize to the same name, append a short path-derived suffix.

Validation

After generation:

1. Run the project formatter if available.
2. Compile at least one generated .nts file with the local ntee-r1quest compiler when available.
3. Check that every ref path exists.
4. Check that every @i(key) is defined by one of the referenced .ntd files, or carries an or default (e.g. @i(content-type or "application/json")).
5. Check that every .nts with a body declares a content-type header.
6. Check that every @f(path) points to an existing example file, or clearly mark the file as a placeholder that the user must provide.

Report:

• generated project path
• number of .nts files
• number of .ntd files
• any skipped operations and why
• validation commands and results