# Basic Prompt.

To be used for simpler cases where all relevant information exists in an easily traversible format.

```markdown
## Task: Generate Swagger/OpenAPI Specification

**Input Variables:**
- `version`: API version (e.g., V3)
- `topic`: API domain/category
- `format`: Path naming convention (e.g., lower-kebab)
- `special concerns`: Additional constraints or context
- `examples`: Sample path patterns

**Instructions:**

Following the instructions in `api_spec_guidelines.mdx` and using the templates in `template.yaml`, generate a complete Swagger-formatted YAML specification.

**Requirements:**
1. Cover all paths and all valid HTTP methods for `{topic}` APIs
2. Use `{format}` path naming convention throughout
3. Include the example path(s) below as a baseline
4. Add any additional paths relevant to `{topic}` beyond the examples

**Examples (baseline minimum):**
{examples}

**Special concerns:**
{special_concerns}

**Version:** {version}
**Topic:** {topic}
**Path format:** {format}

**Output:** Valid YAML following Swagger/OpenAPI 2.0 or 3.0 as specified in `template.yaml`
```

# Basic Prompt Example

```markdown
## Task: Generate Swagger/OpenAPI Specification

**Input Variables:**
- Version: V3
- Topic: Super Admin APIs
- Path format: lower-kebab case
- Special concerns: May be called "Sales Rep" in legacy references — always use "Super Admin" in output

**Instructions:**

Following the instructions in `api_spec_guidelines.mdx` and using the templates in `template.yaml`, generate a complete Swagger-formatted YAML specification.

**Requirements:**
1. Cover all paths and all valid HTTP methods for Super Admin APIs
2. Use lower-kebab case path naming throughout (e.g., `/super-admin`, `/company`, `/companies`)
3. Include the baseline paths below
4. Add any additional paths relevant to Super Admin functionality

**Baseline paths (include these):**
- `/super-admin`
- `/company`
- `/companies`

**Alias handling:**
- Input may refer to "Sales Rep APIs"
- Translate all references to "Super Admin" in output
- Do not output "Sales Rep" terminology

**Output:** Valid YAML following Swagger/OpenAPI format from `template.yaml`
```

# Advanced Prompt.

To be used for more advanced cases when traversibility is impaired or content is obscured by separation of concerns.

```markdown
## Task: Generate Complete OpenAPI Specification from Repository

**Phase 1 — Discovery**
Analyze the attached repository to identify all external HTTP endpoints.

**Phase 2 — Specification Generation**
Following `api_spec_guidelines.mdx` and `template.yaml`, generate a complete OpenAPI specification for `{API family}` APIs.

**Required elements:**
- All external HTTP paths
- All HTTP methods for each path
- Parameters (path, query, header, cookie)
- Request bodies (schemas, examples where available)
- Responses (status codes, schemas)

**Deprecation marking:**
- Mark deprecated operations and fields with `deprecated: true`
- Include deprecation notice in description: "This [object_type] is deprecated. Please use [alternative] instead."

**Reusability:**
- Extract reusable schemas, parameters, and responses into `components` section
- Reference components using `$ref`

**Special concerns:** {special_concerns}

**Output:** Valid OpenAPI 3.x YAML

---

### Specialized Variation: Large API Families (e.g., Catalog)

When `{API family}` contains too many endpoints for single-pass generation (e.g., Catalog):

**Override instruction:** Do not attempt all endpoints. Instead, require specific sub-family selection.

**Example:** Instead of "Catalog/Variants", use "Catalog/Variant Options"

**Workflow:**
1. Prompt for sub-family name
2. Generate spec for sub-family only
3. Indicate remaining families with `# Additional families omitted: [list]`

---

### Single Endpoint Options

For single-endpoint specifications, choose one method:

| Method | Description | Status |
|--------|-------------|--------|
| A | Run standard prompt with explanation, extract endpoint + components from output | Untested |
| B | Use separate prompt template that removes path completeness requirement; output only `paths` and `components` sections | Original, verified |
| C | Extend template and instructions with conditional logic for single-endpoint mode | Ideal, requires separate prompt format |

**Recommendation:** Method B for production use. Method C for future development.
```