openapi: 3.0.3
info:
  title: SeedAPI Online
  version: 1.1.0
  description: |
    ## API Standards Guide
    Application Programming Interface (API) standards are collections of rules, protocols, and standardized formats allowing different software systems to connect, communicate, and exchange data consistently, securely, and efficiently.

    ### 1. Popular API Architectures
    - **REST (Representational State Transfer)**: The most prevalent architectural style running on HTTP, utilizing methods like `GET`, `POST`, `PUT`, `DELETE` to manipulate data resources.
    - **SOAP (Simple Object Access Protocol)**: A highly structured XML-based protocol favored by banks and large enterprises demanding rigorous security standards.
    - **GraphQL**: A modern query language enabling clients to request exactly the data they need, minimizing payloads.

    ### 2. Key Components
    - **Endpoint**: The target URL accessible for API consumption (e.g., `/api/v1/seeds`).
    - **Methods**: Standard actions: `GET` (Fetch), `POST` (Create), `PUT` (Update), `DELETE` (Remove).
    - **Data Format**: Most commonly light-weight and human-readable `JSON`, followed by `XML`.
    - **Authentication**: Security protocols ensuring safety (e.g., `Bearer Token`, `Sanctum`).

    ### 3. API Documentation Standards
    Ensuring developer understandability without exposing source logic:
    - **Descriptions**: Functional overviews of every capability.
    - **Parameters**: Clarification on mandatory vs optional input variables.
    - **Responses**: Structured data schemas and standard semantic status codes (e.g., `200 OK`, `404 Not Found`, `500 Error`).
servers:
  - url: /api
    description: API base
tags:
  - name: Auth
    description: Register and login
  - name: Seed
    description: Free seed data generation
  - name: System
    description: Health and account info
paths:
  /v1/health:
    get:
      tags: [System]
      summary: Health check
      responses:
        "200":
          description: Service is healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
                  service:
                    type: string
                  version:
                    type: string
                    example: v1
  /v1/register:
    post:
      tags: [Auth]
      summary: Register a new account
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - email
                - password
                - password_confirmation
              properties:
                name:
                  type: string
                  example: Demo User
                email:
                  type: string
                  format: email
                  example: demo@example.com
                password:
                  type: string
                  format: password
                  example: password123
                password_confirmation:
                  type: string
                  format: password
                  example: password123
      responses:
        "201":
          description: Account created
        "422":
          description: Validation error
  /v1/login:
    post:
      tags: [Auth]
      summary: Login and receive a bearer token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - password
              properties:
                email:
                  type: string
                  format: email
                  example: demo@example.com
                password:
                  type: string
                  format: password
                  example: password123
      responses:
        "200":
          description: Login success
        "422":
          description: Validation error
  /v1/me:
    get:
      tags: [System]
      summary: Current authenticated user
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Authenticated user
        "401":
          description: Unauthorized
  /v1/logout:
    post:
      tags: [System]
      summary: Revoke the current bearer token
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Token revoked
        "401":
          description: Unauthorized
  /v1/seeds:
    get:
      tags: [Seed]
      summary: Generate seed data
      security:
        - bearerAuth: []
      parameters:
        - name: type
          in: query
          required: false
          schema:
            type: string
            enum: [users, products, articles, companies, orders, reviews, categories, posts, comments, notifications, transactions, credit-cards, currencies, projects, tasks, audit-logs, multimedia, sports, places, weather]
        - name: count
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 25
            example: 10
      responses:
        "200":
          description: Seed data
        "401":
          description: Unauthorized
        "429":
          description: Rate limit exceeded
  /v1/seeds/{type}:
    get:
      tags: [Seed]
      summary: Generate one item for a specific seed type
      security:
        - bearerAuth: []
      parameters:
        - name: type
          in: path
          required: true
          schema:
            type: string
            enum: [users, products, articles, companies, orders, reviews, categories, posts, comments, notifications, transactions, credit-cards, currencies, projects, tasks, audit-logs, multimedia, sports, places, weather]
      responses:
        "200":
          description: Seed data
        "401":
          description: Unauthorized
        "404":
          description: Type not found
        "429":
          description: Rate limit exceeded
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Sanctum token
