OpenAPI (Swagger) 2.0 specification for describing REST APIs. Use when writing, validating, or interpreting Swagger 2.0 specs, generating clients/docs, or working with path/operation/parameter/response/schema/security definitions.
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 |
| 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
| Topic | Description | Reference |
|---|---|---|
| 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
| Topic | Description | Reference |
|---|---|---|
| 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
| Topic | Description | Reference |
|---|---|---|
| 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
| Topic | Description | Reference |
|---|---|---|
| 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
| Topic | Description | Reference |
|---|---|---|
| Spec Authoring | operationId, tags, responses, parameters, definitions, security | best-practices-spec-authoring |
Advanced
| Topic | Description | Reference |
|---|---|---|
| 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 |
You Might Also Like
Related Skills
verify
Use when you want to validate changes before committing, or when you need to check all React contribution requirements.
facebooktest
Use when you need to run tests for React core. Supports source, www, stable, and experimental channels.
facebookfeature-flags
Use when feature flag tests fail, flags need updating, understanding @gate pragmas, debugging channel-specific test failures, or adding new flags to React.
facebookextract-errors
Use when adding new error messages to React, or seeing "unknown error code" warnings.
facebook