tasks/documentation/api_documentation/cases.yaml

cases:
  - id: "openapi_spec"
    question: "Create OpenAPI 3.0 specification for a user management API"
    reference_doc: |
      openapi: 3.0.0
      info:
        title: User Management API
        version: 1.0.0
        description: API for managing users
      servers:
        - url: https://api.example.com/v1
      paths:
        /users:
          get:
            summary: List all users
            responses:
              '200':
                description: List of users
                content:
                  application/json:
                    schema:
                      type: array
                      items:
                        $ref: '#/components/schemas/User'
          post:
            summary: Create a new user
            requestBody:
              required: true
              content:
                application/json:
                  schema:
                    $ref: '#/components/schemas/UserInput'
            responses:
              '201':
                description: User created
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/User'
        /users/{id}:
          get:
            summary: Get user by ID
            parameters:
              - name: id
                in: path
                required: true
                schema:
                  type: integer
            responses:
              '200':
                description: User details
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/User'
      components:
        schemas:
          User:
            type: object
            properties:
              id:
                type: integer
              name:
                type: string
              email:
                type: string
                format: email
          UserInput:
            type: object
            required:
              - name
              - email
            properties:
              name:
                type: string
              email:
                type: string
                format: email
    difficulty: "hard"
    description: "OpenAPI specification"
    
  - id: "graphql_schema"
    question: "Create GraphQL schema for a blog system with posts and comments"
    reference_doc: |
      type Query {
        posts: [Post!]!
        post(id: ID!): Post
        comments(postId: ID!): [Comment!]!
      }
      
      type Mutation {
        createPost(input: PostInput!): Post!
        createComment(input: CommentInput!): Comment!
        updatePost(id: ID!, input: PostInput!): Post!
        deletePost(id: ID!): Boolean!
      }
      
      type Post {
        id: ID!
        title: String!
        content: String!
        author: User!
        comments: [Comment!]!
        createdAt: String!
        updatedAt: String!
      }
      
      type Comment {
        id: ID!
        content: String!
        author: User!
        post: Post!
        createdAt: String!
      }
      
      type User {
        id: ID!
        name: String!
        email: String!
        posts: [Post!]!
        comments: [Comment!]!
      }
      
      input PostInput {
        title: String!
        content: String!
        authorId: ID!
      }
      
      input CommentInput {
        content: String!
        authorId: ID!
        postId: ID!
      }
    difficulty: "medium"
    description: "GraphQL schema definition"
    
  - id: "rest_endpoints"
    question: "Document REST API endpoints for an e-commerce product catalog"
    reference_doc: |
      # Product Catalog API
      
      ## Base URL
      `https://api.store.com/v1`
      
      ## Authentication
      All endpoints require authentication via Bearer token:
      ```
      Authorization: Bearer <your-token>
      ```
      
      ## Endpoints
      
      ### GET /products
      Retrieve a list of products with optional filtering and pagination.
      
      **Query Parameters:**
      - `category` (string, optional): Filter by product category
      - `min_price` (number, optional): Minimum price filter
      - `max_price` (number, optional): Maximum price filter
      - `page` (integer, optional): Page number (default: 1)
      - `limit` (integer, optional): Items per page (default: 20, max: 100)
      
      **Response:**
      ```json
      {
        "products": [
          {
            "id": "prod_123",
            "name": "Wireless Headphones",
            "description": "High-quality wireless headphones",
            "price": 99.99,
            "category": "Electronics",
            "in_stock": true,
            "images": ["https://example.com/img1.jpg"]
          }
        ],
        "pagination": {
          "page": 1,
          "limit": 20,
          "total": 150,
          "pages": 8
        }
      }
      ```
      
      ### GET /products/{id}
      Retrieve a specific product by ID.
      
      **Path Parameters:**
      - `id` (string, required): Product ID
      
      **Response:**
      ```json
      {
        "id": "prod_123",
        "name": "Wireless Headphones",
        "description": "High-quality wireless headphones with noise cancellation",
        "price": 99.99,
        "category": "Electronics",
        "in_stock": true,
        "stock_quantity": 50,
        "images": ["https://example.com/img1.jpg", "https://example.com/img2.jpg"],
        "specifications": {
          "battery_life": "20 hours",
          "connectivity": "Bluetooth 5.0",
          "weight": "250g"
        }
      }
      ```
      
      ### POST /products
      Create a new product (Admin only).
      
      **Request Body:**
      ```json
      {
        "name": "New Product",
        "description": "Product description",
        "price": 49.99,
        "category": "Electronics",
        "stock_quantity": 100,
        "images": ["https://example.com/img.jpg"]
      }
      ```
      
      **Response:** `201 Created`
      ```json
      {
        "id": "prod_456",
        "name": "New Product",
        "description": "Product description",
        "price": 49.99,
        "category": "Electronics",
        "in_stock": true,
        "stock_quantity": 100,
        "images": ["https://example.com/img.jpg"],
        "created_at": "2023-12-01T10:00:00Z"
      }
      ```
    difficulty: "hard"
    description: "Comprehensive REST API documentation"