openapi-authoring

# OpenAPI Authoring Skill

## When to Use This Skill

Use this skill when:

- **Openapi Authoring tasks** - Working on author and validate openapi 3.1 specifications for rest api design, following api-first and contract-first development practices
- **Planning or design** - Need guidance on Openapi Authoring approaches
- **Best practices** - Want to follow established patterns and standards

## Overview

Author OpenAPI 3.1 specifications for REST API design using API-first methodology.

## OpenAPI 3.1 Structure

### Root Document

```yaml
openapi: "3.1.0"

info:
  title: "{Service Name} API"
  version: "1.0.0"
  description: |
    {Service description and purpose}
  contact:
    name: "{Team Name}"
    email: "{team@company.com}"
  license:
    name: "MIT"
    identifier: "MIT"

servers:
  - url: "https://api.example.com/v1"
    description: "Production"
  - url: "https://api.staging.example.com/v1"
    description: "Staging"
  - url: "http://localhost:5000/v1"
    description: "Local development"

tags:
  - name: "{Resource}"
    description: "Operations for {resource} management"

paths:
  # Path definitions

components:
  # Reusable components

security:
  - bearerAuth: []
```

### Path Operations

```yaml
paths:
  /resources:
    get:
      operationId: "listResources"
      summary: "List all resources"
      description: "Retrieves a paginated list of resources"
      tags:
        - Resources
      parameters:
        - $ref: "#/components/parameters/PageNumber"
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/SortBy"
      responses:
        "200":
          description: "Successful response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResourceListResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"

    post:
      operationId: "createResource"
      sum