openapi-authoring

What this skill does

# 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: "{[email protected]}"
  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"
      summary: "Create a new resource"
      description: "Creates a new resource with the provided data"
      tags:
        - Resources
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateResourceRequest"
      responses:
        "201":
          description: "Resource created"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResourceResponse"
          headers:
            Location:
              description: "URL of the created resource"
              schema:
                type: string
                format: uri
        "400":
          $ref: "#/components/responses/BadRequest"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"

  /resources/{resourceId}:
    parameters:
      - $ref: "#/components/parameters/ResourceId"

    get:
      operationId: "getResource"
      summary: "Get a resource by ID"
      description: "Retrieves a single resource by its unique identifier"
      tags:
        - Resources
      responses:
        "200":
          description: "Successful response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResourceResponse"
        "404":
          $ref: "#/components/responses/NotFound"

    put:
      operationId: "updateResource"
      summary: "Update a resource"
      description: "Replaces the entire resource with the provided data"
      tags:
        - Resources
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateResourceRequest"
      responses:
        "200":
          description: "Resource updated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResourceResponse"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"

    patch:
      operationId: "patchResource"
      summary: "Partially update a resource"
      description: "Updates specific fields of the resource"
      tags:
        - Resources
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PatchResourceRequest"
      responses:
        "200":
          description: "Resource patched"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResourceResponse"
        "404":
          $ref: "#/components/responses/NotFound"

    delete:
      operationId: "deleteResource"
      summary: "Delete a resource"
      description: "Permanently removes a resource"
      tags:
        - Resources
      responses:
        "204":
          description: "Resource deleted"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
```

### Component Schemas

```yaml
components:
  schemas:
    # Request schemas
    CreateResourceRequest:
      type: object
      required:
        - name
        - type
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 100
          description: "Resource name"
          example: "My Resource"
        type:
          $ref: "#/components/schemas/ResourceType"
        description:
          type: string
          maxLength: 500
          description: "Optional description"
        metadata:
          type: object
          additionalProperties: true
          description: "Custom metadata key-value pairs"

    UpdateResourceRequest:
      allOf:
        - $ref: "#/components/schemas/CreateResourceRequest"

    PatchResourceRequest:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 100
        description:
          type: string
          maxLength: 500
      minProperties: 1

    # Response schemas
    ResourceResponse:
      type: object
      required:
        - id
        - name
        - type
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          format: uuid
          description: "Unique identifier"
          example: "550e8400-e29b-41d4-a716-446655440000"
        name:
          type: string
          description: "Resource name"
        type:
          $ref: "#/components/schemas/ResourceType"
        description:
          type: string
        metadata:
          type: object
          additionalProperties: true
        createdAt:
          type: string
          format: date-time
          description: "Creation timestamp (ISO 8601)"
        updatedAt:
          type: string
          format: date-time
          description: "Last update timestamp (ISO 8601)"
        _links:
          $ref: "#/components/schemas/ResourceLinks"

    ResourceListResponse:
      type: object
      required:
        - data
        - pagination
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/ResourceResponse"
        pagination:
          $ref: "#/components/schemas/Pagination"
        _links:
          $ref: "#/components/schemas/PaginationLinks"

    # Enums
    ResourceType:
      type: string
      enum:
        - standard
        - premium
        - enterprise
      description: "Type of resource"

    # Common schemas
    Pagination:
      type: object
      required:
        - page
        - pageSize
        - totalItems
        - totalPages
      properties:
        page:
          type: integer
          minimum: 1
          description: "Current page number"
        pageSize:
          type: integer
          minimum: 1
          maximum: 100
          description: "Items per page"
        totalItems:
          type: integer
          minimum: