1---
2name: openapi-specification-v2
3description: 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.
4metadata:
5 author: hairy
6 version: "2026.1.30"
7 source: Generated from https://github.com/OAI/OpenAPI-Specification, scripts located at https://github.com/antfu/skills
8---
9
10OpenAPI 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.
11
12> The skill is based on OpenAPI Specification 2.0, generated at 2026-01-30.
13
14## Core References
15
16| Topic | Description | Reference |
17|-------|-------------|-----------|
18| Format and Structure | Document format, file structure, data types | [core-format-and-structure](references/core-format-and-structure.md) |
19| Fixed and Patterned Fields | Fixed vs patterned field names in the schema | [core-fixed-patterned-fields](references/core-fixed-patterned-fields.md) |
20| Swagger Object | Root document, required/optional fields, extensions | [core-swagger-object](references/core-swagger-object.md) |
21| Info and Metadata | Info, Contact, License objects | [core-info-metadata](references/core-info-metadata.md) |
22| Tags and External Docs | Tag Object, External Documentation Object | [core-tags-and-external-docs](references/core-tags-and-external-docs.md) |
23| Reference Object | $ref, JSON Pointer, same-document and external file references | [core-reference-object](references/core-reference-object.md) |
24| Data Types and Formats | Primitives, format table, validation, file type | [core-data-types-and-formats](references/core-data-types-and-formats.md) |
25| MIME Types | consumes/produces, RFC 6838, examples | [core-mime-types](references/core-mime-types.md) |
26| HTTP Status Codes | Response keys, default response, IANA/RFC 7231 | [core-http-status-codes](references/core-http-status-codes.md) |
27| Path Templating | Curly braces, path parameters, name matching | [core-path-templating](references/core-path-templating.md) |
28| Header Object | Response header definition (type, format, items, validation) | [core-header-object](references/core-header-object.md) |
29| Headers Object | Container for response headers (name → Header Object) | [core-headers-object](references/core-headers-object.md) |
30| Items Object | Non-body array items (parameters, headers) | [core-items-object](references/core-items-object.md) |
31| Example Object | Response examples by MIME type | [core-example-object](references/core-example-object.md) |
32
33## Paths and Operations
34
35| Topic | Description | Reference |
36|-------|-------------|-----------|
37| Paths and Operations | Paths Object, Path Item, Operation Object | [paths-and-operations](references/paths-and-operations.md) |
38| Path Item $ref | External path definition, conflict behavior | [path-item-ref](references/path-item-ref.md) |
39
40## Parameters and Responses
41
42| Topic | Description | Reference |
43|-------|-------------|-----------|
44| Parameters | Parameter locations (path, query, header, body, formData) | [parameters](references/parameters.md) |
45| collectionFormat | csv, ssv, tsv, pipes, multi and where they apply | [parameters-collection-format](references/parameters-collection-format.md) |
46| Parameters Definitions (Reuse) | Root-level parameters, reuse via $ref | [parameters-definitions-reuse](references/parameters-definitions-reuse.md) |
47| Responses | Responses Object, Response Object | [responses](references/responses.md) |
48| Responses Definitions (Reuse) | Root-level responses, reuse via $ref | [responses-definitions-reuse](references/responses-definitions-reuse.md) |
49
50## Schemas and Definitions
51
52| Topic | Description | Reference |
53|-------|-------------|-----------|
54| Schema and Definitions | Schema Object, Definitions, composition, polymorphism | [schema-and-definitions](references/schema-and-definitions.md) |
55| Schema JSON Schema Keywords | JSON Schema Draft 4 subset and Swagger-specific fields | [schema-json-schema-keywords](references/schema-json-schema-keywords.md) |
56
57## Security
58
59| Topic | Description | Reference |
60|-------|-------------|-----------|
61| Security | Security Definitions, Security Scheme | [security](references/security.md) |
62| Security Requirement Object | Applying security at root/operation, OR/AND logic | [security-requirement-object](references/security-requirement-object.md) |
63| Scopes Object | OAuth2 scope name → description | [security-scopes-object](references/security-scopes-object.md) |
64| Basic and API Key | basic and apiKey Security Scheme | [security-basic-apikey](references/security-basic-apikey.md) |
65| OAuth2 Flows | implicit, password, application, accessCode and required URLs | [security-oauth2-flows](references/security-oauth2-flows.md) |
66
67## Best Practices
68
69| Topic | Description | Reference |
70|-------|-------------|-----------|
71| Spec Authoring | operationId, tags, responses, parameters, definitions, security | [best-practices-spec-authoring](references/best-practices-spec-authoring.md) |
72
73## Advanced
74
75| Topic | Description | Reference |
76|-------|-------------|-----------|
77| Vendor Extensions | x- prefix, value types, where allowed | [advanced-vendor-extensions](references/advanced-vendor-extensions.md) |
78| Security Filtering | Empty Paths, empty Path Item for access control | [advanced-security-filtering](references/advanced-security-filtering.md) |
79| Extensions and XML | XML Object for schema properties | [advanced-extensions-and-xml](references/advanced-extensions-and-xml.md) |
hairyf