version: 1
kind: action
name: API Design
description: Comprehensive API design and documentation with OpenAPI specification, testing, and best practices implementation
prompt: |
  Design and implement comprehensive RESTful APIs with industry best practices.
  Create complete API solutions including OpenAPI 3.0 specifications and endpoint implementation.
  Follow REST principles and generate automated tests for all endpoints.
  Include authentication, validation, error handling, and comprehensive documentation.
enhanced-prompt: |-
  # 🔌 API Design Workflow

  ## Project Setup & Planning
  ```bash
  # Create API structure
  mkdir -p api/{specs,docs,tests,controllers,models}

  # Initialize OpenAPI spec
  cat > api/specs/openapi.yaml << EOF
  openapi: 3.0.3
  info:
    title: $(basename $(pwd)) API
    version: 1.0.0
    description: RESTful API with comprehensive documentation
  servers:
    - url: http://localhost:3000/api/v1
  paths: {}
  components:
    schemas: {}
  EOF
  ```

  ## Define API Endpoints
  ```bash
  # Add basic CRUD endpoints to OpenAPI spec
  # GET /users - List users
  # POST /users - Create user  
  # GET /users/{id} - Get user
  # PUT /users/{id} - Update user
  # DELETE /users/{id} - Delete user

  # Add schemas for User, Error, Pagination
  # Include authentication (Bearer token)
  # Define proper HTTP status codes
  ```

  ## Implementation & Testing
  ```bash
  # Generate API documentation
  npx swagger-ui-serve api/specs/openapi.yaml

  # Create test suite
  cat > api/tests/api.test.js << EOF
  const request = require('supertest');
  const app = require('../app');

  describe('API Tests', () => {
    test('GET /health returns 200', async () => {
      await request(app).get('/api/v1/health').expect(200);
    });
  });
  EOF

  # Run tests
  npm test
  ```

  ## Documentation & Validation
  ```bash
  # Validate OpenAPI spec
  npx swagger-codegen validate -i api/specs/openapi.yaml

  # Generate API client
  npx openapi-generator-cli generate -i api/specs/openapi.yaml -g javascript

  # Create README
  echo "# API Documentation" > api/docs/README.md
  echo "OpenAPI spec: /api/specs/openapi.yaml" >> api/docs/README.md
  ```

  **🎯 Result:** Complete RESTful API with OpenAPI documentation and tests