spec-writing-openapi

michaellperry's avatarfrom michaellperry

Writes complete OpenAPI 3.0 specifications for API endpoints following RESTful conventions. Use when creating new API endpoints, documenting API contracts, or defining request/response schemas for GloboTicket APIs.

⭐0stars🔀0forks📁View on GitHub🕐Updated Jan 11, 2026
[API Helpers]

When & Why to Use This Skill

This Claude skill automates the creation of comprehensive OpenAPI 3.0 specifications, ensuring all API endpoints adhere to RESTful conventions. It streamlines the development workflow by generating detailed request/response schemas, security definitions, and validation rules, making it an essential tool for maintaining high-quality API documentation and contracts.

Use Cases

  • Designing new API endpoints: Rapidly scaffold standardized OpenAPI definitions for new features to ensure consistency across the codebase.
  • Documenting API contracts: Create clear and precise technical documentation that serves as a single source of truth for frontend and backend synchronization.
  • Defining data schemas: Automatically generate complex request and response objects with specific validation rules, data types, and example values.
  • Standardizing security protocols: Implement consistent security schemes, such as cookie-based authentication or API keys, across all documented endpoints.
namespec-writing-openapi
descriptionWrites complete OpenAPI 3.0 specifications for API endpoints following RESTful conventions. Use when creating new API endpoints, documenting API contracts, or defining request/response schemas for GloboTicket APIs.

OpenAPI Specification

Provide complete OpenAPI 3.0 definitions for ALL new or modified endpoints:

openapi: 3.0.0
info:
  title: GloboTicket API - [Feature Name]
  version: 1.0.0

paths:
  /api/resource:
    post:
      summary: Create new resource
      tags:
        - Resource
      security:
        - cookieAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateResourceRequest'
      responses:
        '201':
          description: Resource created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceResponse'
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
        '429':
          description: Rate limit exceeded

components:
  schemas:
    CreateResourceRequest:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          maxLength: 100
          example: "Resource Name"
    
    ResourceResponse:
      type: object
      properties:
        id:
          type: integer
          format: int32
        entityGuid:
          type: string
          format: uuid
        name:
          type: string
        createdAt:
          type: string
          format: date-time
  
  securitySchemes:
    cookieAuth:
      type: apiKey
      in: cookie
      name: .GloboTicket.Auth

API Design Principles

  • Use RESTful conventions (GET, POST, PUT, DELETE)
  • Return appropriate status codes (201 for created, 204 for no content)
  • Follow existing endpoint patterns in codebase
  • Require authorization by default
  • Specify all validation rules and constraints
  • Document error responses (400, 401, 403, 404, 429, 500)