OpenAPI/Swagger Specification Generator

## ROLE

You are an API specification expert who has written and maintained OpenAPI specifications for APIs with hundreds of endpoints across multiple industries. You understand the full OpenAPI 3.0 and 3.1 specification, including advanced features like discriminators, callbacks, links, and webhooks. You write specifications that serve as the single source of truth for code generation (server stubs and client SDKs), automated testing, interactive documentation (Swagger UI, Redoc, Stoplight), and API governance validation. You optimize specs for both human readability and machine processing.

## OBJECTIVE

Generate a complete OpenAPI 3.1 specification for [API NAME] — a [API TYPE: REST / RESTful with hypermedia / JSON:API compliant] API for [DOMAIN: e-commerce / fintech / healthcare / SaaS / logistics / social / education / developer tools / IoT]. The API has [ENDPOINT COUNT: 10-20 / 20-50 / 50-100] endpoints organized around [RESOURCE COUNT: 5-15] core resources. The specification must support code generation in [LANGUAGES: TypeScript / Python / Java / Go / Ruby / C# / Swift / Kotlin], power interactive documentation with [DOCS TOOL: Swagger UI / Redoc / Stoplight Elements], and serve as input for contract testing with [TEST TOOL: Dredd / Schemathesis / Prism / custom]. The API uses [AUTH: API key / OAuth 2.0 / JWT / multiple].

## TASK: COMPLETE OPENAPI SPECIFICATION

### Info, Servers & Global Configuration
Write the OpenAPI info section with a compelling API description (2-3 paragraphs in Markdown) that covers what the API does, who it is for, key features, and a quick start guide embedded in the description. Define the terms of service URL, contact information (name, email, URL), and license (MIT, Apache 2.0, proprietary). Configure server objects for each environment: production (https://api.[DOMAIN].com/v1), staging (https://api-staging.[DOMAIN].com/v1), sandbox (https://sandbox-api.[DOMAIN].com/v1), and local development (http://localhost:[PORT]/v1). Use server variables for parameterized URLs where appropriate (e.g., region selection). Set global security requirements and define tags with descriptions for every resource group, ordered logically for the documentation navigation sidebar.

### Security Schemes
Define every authentication mechanism the API supports. For API key authentication, specify the header name (X-API-Key or Authorization), the in location (header, query, cookie), and provide a description with instructions for obtaining a key. For OAuth 2.0, define the complete flow configuration: authorization URL, token URL, refresh URL, and scopes with descriptions for each scope (e.g., "orders:read — Read access to orders", "orders:write — Create and modify orders"). For JWT bearer tokens, specify the bearerFormat and describe the token structure and claims. For each security scheme, provide an x-example extension showing a realistic (but fake) credential value for documentation purposes. Document how to combine security schemes (OR for alternative auth methods, AND for layered auth).

### Schema Components & Data Models
Define reusable schema components for every resource and sub-resource. For each schema, use proper JSON Schema features: required fields, format annotations (date-time, email, uri, uuid), pattern constraints for strings, minimum/maximum for numbers, minLength/maxLength for strings, enum for fixed value sets, and nullable where appropriate. Implement schema composition: use allOf for inheritance (BaseResource with id, created_at, updated_at extended by specific resources), oneOf or anyOf for polymorphic responses with discriminator mappings, and $ref for shared components (Address, Money, Pagination). Define separate schemas for create (request body, omitting server-generated fields), update (request body with all fields optional for PATCH), and response (complete resource with all fields). Provide a rich example value for every schema using the example or examples keyword — use realistic data, not placeholder text. Create [NUMBER: 8-15] schema components covering your core resources, and list every field with its type, description, constraints, and example value.

### Path Operations & Endpoints
Define every API endpoint with complete path operation objects. For each endpoint, specify: the HTTP method and path, operationId (unique, camelCase, descriptive — e.g., listUsers, createOrder, getOrderById), a one-line summary and a detailed description in Markdown, the tag(s) it belongs to, all path parameters (with schema, description, required, and example), all query parameters for list endpoints (pagination, filtering, sorting, field selection — each with schema, description, required, default value, and example), the request body with content type and schema reference (for POST, PUT, PATCH), all possible response status codes (200, 201, 204, 400, 401, 403, 404, 409, 422, 429, 500) with response schema references and realistic example responses, and security requirements if different from the global default. Group related endpoints under the same tag and order operations logically within each tag: list (GET collection), create (POST), get (GET single), update (PUT/PATCH), delete (DELETE), then custom actions. Provide complete specifications for [NUMBER: 15-25] endpoints across [NUMBER: 5-8] resource groups.

### Examples, Links & Callbacks
Add rich examples to every endpoint. Use the examples keyword (not just example) to provide multiple named examples per operation: a minimal example showing required fields only, a complete example showing all fields, and edge case examples showing boundary values or empty collections. For related endpoints, define link objects that describe the relationship: after creating an order (POST /orders), the response links to getting the order (GET /orders/{orderId}) with the runtime expression $response.body#/id mapped to the orderId parameter. If the API supports webhooks, define callback objects for each event type: the webhook URL template (using runtime expressions from the subscription), the request body schema (matching the event payload), and the expected response. Implement examples for error responses that show realistic validation error structures with field-level details.

### Documentation Extensions & Governance
Add custom extensions that enhance the developer experience: x-codegen-request-body-name for clean method signatures in generated SDKs, x-code-samples with example requests in [NUMBER: 3-5] languages (curl, JavaScript, Python, Go, Ruby), x-internal for marking endpoints not shown in public documentation, and x-deprecated-at with the date an endpoint was deprecated. Implement specification linting rules using [TOOL: Spectral / Redocly / custom] to enforce: all operations must have operationId, all parameters must have descriptions and examples, all schemas must have descriptions, all error responses must use the standard error schema, no inline schemas in path operations (use $ref instead), consistent naming conventions, and security must be defined on every operation. Provide the complete linting ruleset configuration. Generate a specification quality report: percentage of endpoints with complete examples, percentage of schemas with descriptions on all fields, and any linting violations to resolve.