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
| 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
| Headers Object | Container for response headers (name → Header Object) | core-headers-object
| Items Object | Non-body array items (parameters, headers) | core-items-object
| Example Object | Response examples by MIME type | core-example-object
Paths and Operations
| Paths and Operations | Paths Object, Path Item, Operation Object | paths-and-operations
| Path Item $ref | External path definition, conflict behavior | path-item-ref
Parameters and Responses
| Parameters | Parameter locations (path, query, header, body, formData) | parameters
| collectionFormat | csv, ssv, tsv, pipes, multi and where they apply | parameters-collection-format
| Parameters Definitions (Reuse) | Root-level parameters, reuse via $ref | parameters-definitions-reuse
| Responses | Responses Object, Response Object | responses
| Responses Definitions (Reuse) | Root-level responses, reuse via $ref | responses-definitions-reuse
Schemas and Definitions
| Schema and Definitions | Schema Object, Definitions, composition, polymorphism | schema-and-definitions
| Schema JSON Schema Keywords | JSON Schema Draft 4 subset and Swagger-specific fields | schema-json-schema-keywords
Security
| Security | Security Definitions, Security Scheme | security
| Security Requirement Object | Applying security at root/operation, OR/AND logic | security-requirement-object
| Scopes Object | OAuth2 scope name → description | security-scopes-object
| Basic and API Key | basic and apiKey Security Scheme | security-basic-apikey
| OAuth2 Flows | implicit, password, application, accessCode and required URLs | security-oauth2-flows
Best Practices
| Spec Authoring | operationId, tags, responses, parameters, definitions, security | best-practices-spec-authoring
Advanced
| Vendor Extensions | x- prefix, value types, where allowed | advanced-vendor-extensions
| Security Filtering | Empty Paths, empty Path Item for access control | advanced-security-filtering
| Extensions and XML | XML Object for schema properties | advanced-extensions-and-xml