openapi-specification-v2
Complete reference for writing, validating, and interpreting OpenAPI Specification 2.0 (Swagger) documents.
- Covers all core schema elements: Swagger Object root, Info/Contact/License metadata, Paths, Operations, Parameters (path, query, header, body, formData), Responses, and Schemas with composition and polymorphism support
- Includes security definitions for Basic auth, API Key, and OAuth2 flows (implicit, password, application, accessCode) with scope and requirement objects
- Provides reference guidance for $ref usage, JSON Pointers, external file references, and root-level parameter/response/schema reuse
- Addresses data types, formats, MIME types, HTTP status codes, path templating, headers, and vendor extensions (x- prefix)
- Includes best practices for operationId, tags, responses, and spec authoring patterns
OpenAPI Specification 2.0 (formerly Swagger 2.0) defines a JSON/YAML format for describing RESTful APIs: paths, operations, parameters, responses, schemas, and security. Use this skill when creating or editing Swagger 2.0 specs, validating structure, or generating code/documentation from them.
The skill is based on OpenAPI Specification 2.0, generated at 2026-01-30.
Core References
| Topic | Description | Reference |
|---|---|---|
| Format and Structure | Document format, file structure, data types | core-format-and-structure |
| Fixed and Patterned Fields | Fixed vs patterned field names in the schema | core-fixed-patterned-fields |
| Swagger Object | Root document, required/optional fields, extensions | core-swagger-object |
| Info and Metadata | Info, Contact, License objects | core-info-metadata |
| Tags and External Docs | Tag Object, External Documentation Object | core-tags-and-external-docs |
| Reference Object | $ref, JSON Pointer, same-document and external file references | core-reference-object |
| Data Types and Formats | Primitives, format table, validation, file type | core-data-types-and-formats |
| MIME Types | consumes/produces, RFC 6838, examples | core-mime-types |
| HTTP Status Codes | Response keys, default response, IANA/RFC 7231 | core-http-status-codes |
| Path Templating | Curly braces, path parameters, name matching | core-path-templating |
| Header Object | Response header definition (type, format, items, validation) | core-header-object |
More from hairyf/skills
tailwindcss
Tailwind CSS utility-first CSS framework. Use when styling web applications with utility classes, building responsive designs, or customizing design systems with theme variables.
1.7Khairy-utils
Comprehensive skills for working with @hairy/utils core utilities
891motion
Motion animation library for JavaScript, React and Vue. Use when creating animations, gestures, layout transitions, scroll-linked effects, or working with motion values and animation controls.
763next
Next.js framework for building React applications with App Router, Server Components, and optimized performance. Use when working with Next.js apps, routing, data fetching, caching, Server Actions, or building full-stack React applications.
714react-use
Collection of essential React Hooks for sensors, UI, animations, side-effects, lifecycles, and state management
692valtio
Valtio proxy state management for React and vanilla JavaScript. Use when creating reactive state, managing application state, or working with proxy-based state management.
636