openapi: 3.0.3

info:
  title: HTTB.dev API Docs
  version: unstable
  description: "HTTB is a modern HTTP bin. Test your HTTP client or proxy with various HTTP methods, status codes, and more."
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: "https://httb.dev"
    description: "Official HTTB Server"
  - url: http://localhost:{port}
    description: Local HTTB server
    variables:
      port:
        default: "8080"
        description: "Port of the local server"
  - url: "{custom}"
    description: Custom HTTB server
    variables:
      custom:
        default: "http://localhost:8080"
        description: "URL of the custom server"

paths:
  # --- Special Endpoints ---
  /ping:
    get:
      tags:
        - Meta
      summary: Returns "pong"
      description: This endpoint always returns "pong". You can specify the response format.
      parameters:
        - $ref: '#/components/parameters/FormatParam'
        - $ref: '#/components/parameters/DelayParam'
      responses:
        '200':
          description: "Returns `pong`."
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: "pong"
                    example: "pong"
            text/plain:
              example: "pong"
              schema:
                type: string

  # --- JSON Endpoints ---
  /json/random:
    get:
      tags:
        - JSON
      summary: Returns random JSON data.
      description: Returns JSON data.
      parameters:
        - $ref: '#/components/parameters/DelayParam'
        - name: maxDepth
          in: query
          description: "Maximum depth of the JSON object"
          schema:
            type: integer
            minimum: 1
            maximum: 5
            default: 3
          x-oapi-codegen-extra-tags:
            validate: gt=1,lte=5
            default: "3"
        - name: minDepth
          in: query
          description: "Minimum depth of the JSON object"
          schema:
            type: integer
            minimum: 1
            maximum: 3
            default: 1
          x-oapi-codegen-extra-tags:
            validate: gt=0,lte=3
            default: "1"
        - name: maxElems
          in: query
          description: "Maximum number of elements per JSON object"
          schema:
            type: integer
            minimum: 1
            maximum: 10
            default: 3
          x-oapi-codegen-extra-tags:
            validate: gt=0,lte=10
            default: "3"
      responses:
        '200':
          description: JSON data.
          content:
            application/json:
              schema:
                type: object

  /json/random/log:
    get:
      tags:
        - JSON
      summary: Returns random log data.
      description: Returns log data.
      parameters:
        - $ref: '#/components/parameters/DelayParam'
        - $ref: '#/components/parameters/LogLevels'
        - $ref: '#/components/parameters/LogLevelWeights'
        - name: count
          in: query
          description: "Number of log entries to return (min: 1; max: 10000)"
          schema:
            type: integer
            minimum: 1
            maximum: 10000
            default: 10
          x-oapi-codegen-extra-tags:
            validate: gt=1,lte=10000
            default: "10"
      responses:
        '200':
          description: Log data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Log'

  /json/random/address:
    get:
      tags:
        - JSON
      summary: Returns random address data.
      description: Returns address data.
      parameters:
        - $ref: '#/components/parameters/DelayParam'
      responses:
        '200':
          description: Address data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Address'

  /json/random/addresses:
    get:
      tags:
        - JSON
      summary: Returns random address data.
      description: Returns address data.
      parameters:
        - $ref: '#/components/parameters/DelayParam'
        - $ref: '#/components/parameters/Count'
      responses:
        '200':
          description: Address data.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Address'

  /json/random/contact:
    get:
      tags:
        - JSON
      summary: Returns random contact data.
      description: Returns contact data.
      parameters:
        - $ref: '#/components/parameters/DelayParam'
      responses:
        '200':
          description: Contact data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'

  /json/random/contacts:
    get:
      tags:
        - JSON
      summary: Returns random contact data.
      description: Returns contact data.
      parameters:
        - $ref: '#/components/parameters/DelayParam'
        - $ref: '#/components/parameters/Count'
      responses:
        '200':
          description: Contact data.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Contact'

  /json/random/user:
    get:
      tags:
        - JSON
      summary: Returns random user data.
      description: Returns user data.
      parameters:
        - $ref: '#/components/parameters/DelayParam'
      responses:
        '200':
          description: User data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

  /json/random/users:
    get:
      tags:
        - JSON
      summary: Returns random user data.
      description: Returns user data.
      parameters:
        - $ref: '#/components/parameters/DelayParam'
        - $ref: '#/components/parameters/Count'
      responses:
        '200':
          description: User data.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        '400':
          description: Bad request - validation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'

  # --- Streaming Endpoints ---
  /stream/json/user:
    get:
      tags:
        - JSON
        - Stream
      summary: "Streams JSON data."
      description: "Streams JSON data."
      parameters:
        - $ref: '#/components/parameters/DelayParam'
        - $ref: '#/components/parameters/StreamInterval'
      responses:
        '200':
          description: "JSON data."
          content:
            application/json:
              schema:
                type: object


  /stream/json/logs:
    get:
      tags:
        - JSON
        - Stream
      summary: "Streams JSON logs."
      description: "Streams JSON logs."
      parameters:
        - $ref: '#/components/parameters/DelayParam'
        - $ref: '#/components/parameters/LogLevels'
        - $ref: '#/components/parameters/LogLevelWeights'
        - $ref: '#/components/parameters/StreamInterval'
      responses:
        '200':
          description: "JSON logs."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Log'

  # --- Return Request Data ---
  /return:
    get:
      tags:
        - Return Request Data
      summary: "Returns the request data as JSON"
      parameters:
        - $ref: '#/components/parameters/DelayParam'
      requestBody:
        content:
          '*/*':
            schema:
              type: string
      responses:
        '200':
          description: "Request data"
          content:
            application/json:
              schema:
                type: object
    post:
      tags:
        - Return Request Data
      summary: "Returns the request data as JSON"
      parameters:
        - $ref: '#/components/parameters/DelayParam'
      requestBody:
        content:
          '*/*':
            schema:
              type: string
      responses:
        '200':
          description: "Request data"
          content:
            application/json:
              schema:
                type: object
    put:
      tags:
        - Return Request Data
      summary: "Returns the request data as JSON"
      parameters:
        - $ref: '#/components/parameters/DelayParam'
      requestBody:
        content:
          '*/*':
            schema:
              type: string
      responses:
        '200':
          description: "Request data"
          content:
            application/json:
              schema:
                type: object
    patch:
      tags:
        - Return Request Data
      summary: "Returns the request data as JSON"
      parameters:
        - $ref: '#/components/parameters/DelayParam'
      requestBody:
        content:
          '*/*':
            schema:
              type: string
      responses:
        '200':
          description: "Request data"
          content:
            application/json:
              schema:
                type: object
    delete:
      tags:
        - Return Request Data
      summary: "Returns the request data as JSON"
      parameters:
        - $ref: '#/components/parameters/DelayParam'
      requestBody:
        content:
          '*/*':
            schema:
              type: string
      responses:
        '200':
          description: "Request data"
          content:
            application/json:
              schema:
                type: object

  # --- Status ---
  /status/{code}:
    parameters:
      - name: code
        in: path
        description: "HTTP status code that should be returned."
        required: true
        schema:
          type: integer
          minimum: 100
          maximum: 599
    get:
      tags:
        - Status Codes
      summary: "Returns the specified HTTP status code and status message"
      parameters:
        - $ref: '#/components/parameters/DelayParam'
      responses:
        default:
          description: "HTTP status code and status message"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusCodeMessage'
    post:
      tags:
        - Status Codes
      summary: "Returns the specified HTTP status code and status message"
      parameters:
        - $ref: '#/components/parameters/DelayParam'
      responses:
        default:
          description: "HTTP status code and status message"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusCodeMessage'
    put:
      tags:
        - Status Codes
      summary: "Returns the specified HTTP status code and status message"
      parameters:
        - $ref: '#/components/parameters/DelayParam'
      responses:
        default:
          description: "HTTP status code and status message"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusCodeMessage'
    patch:
      tags:
        - Status Codes
      summary: "Returns the specified HTTP status code and status message"
      parameters:
        - $ref: '#/components/parameters/DelayParam'
      responses:
        default:
          description: "HTTP status code and status message"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusCodeMessage'
    delete:
      tags:
        - Status Codes
      summary: "Returns the specified HTTP status code and status message"
      parameters:
        - $ref: '#/components/parameters/DelayParam'
      responses:
        default:
          description: "HTTP status code and status message"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusCodeMessage'

components:
  schemas:
    StatusCodeMessage:
      description: "Status code and status message"
      type: object
      properties:
        message:
          type: string
          example: "Not Found"
          description: "Status code message"
        status:
          type: integer
          description: "Status code"
          example: 404
          minimum: 100
          maximum: 599
    Address:
      type: object
      properties:
        street:
          type: string
          example: "1234 Elm St."
          x-oapi-codegen-extra-tags:
            fake: "{street}"
        city:
          type: string
          example: "Springfield"
          x-oapi-codegen-extra-tags:
            fake: "{city}"
        zip:
          type: string
          example: "62701"
          x-oapi-codegen-extra-tags:
            fake: "{zip}"
    Contact:
      type: object
      properties:
        email:
          type: string
          format: email
          x-oapi-codegen-extra-tags:
            fake: "{email}"
        phone:
          type: string
          format: phone
          x-oapi-codegen-extra-tags:
            fake: "{phone}"
    User:
      type: object
      properties:
        firstName:
          type: string
          example: "John"
          x-oapi-codegen-extra-tags:
            fake: "{firstname}"
        lastName:
          type: string
          example: "Doe"
          x-oapi-codegen-extra-tags:
            fake: "{lastname}"
        age:
          type: integer
          minimum: 0
          maximum: 100
          example: 42
          x-oapi-codegen-extra-tags:
            fake: "{number:0,100}"
        gender:
          type: string
          enum:
            - male
            - female
            - other
          x-oapi-codegen-extra-tags:
            fake: "{randomstring:[male,female,other]}"
        contact:
          $ref: '#/components/schemas/Contact'
        address:
          $ref: '#/components/schemas/Address'
    ValidationError:
      type: object
      properties:
        status_code:
          type: integer
        message:
          type: string
        errors:
          $ref: '#/components/schemas/ValidationMessages'
      required:
        - status_code
        - message
    ValidationMessages:
      type: array
      items:
        $ref: '#/components/schemas/ValidationMessage'
    ValidationMessage:
      type: object
      properties:
        field:
          type: string
        message:
          type: string
      required:
        - field
        - message
    Log:
      type: object
      properties:
        level:
          type: string
          example: "info"
          x-oapi-codegen-extra-tags:
            fake: "{weighted:[debug,info,warn,error],[1,5,3,2]}"
        message:
          type: string
          example: "We need to calculate the virtual PNG capacitor!"
          x-oapi-codegen-extra-tags:
            fake: "{hackerphrase}"
        timestamp:
          type: string
          format: date-time

  parameters:
    FormatParam:
      name: format
      in: query
      description: "Response format (default: `json`)"
      required: false
      schema:
        type: string
        enum: [ json, text ]
        default: json
      x-oapi-codegen-extra-tags:
        validate: oneof=json text
        default: "json"
    DelayParam:
      name: delay
      in: query
      description: "Delay in milliseconds before the response is sent (min: 0; max: 10000)"
      required: false
      schema:
        type: integer
        minimum: 0
        maximum: 10000
        default: 0
    StatusParam:
      name: status
      in: query
      description: "HTTP status code that should be returned."
      schema:
        type: integer
        minimum: 100
        maximum: 599
        default: 200
      x-oapi-codegen-extra-tags:
        validate: gt=100,lte=599
        default: "200"
    LogLevels:
      name: logLevels
      in: query
      description: "Log levels to use (default: `debug,info,warn,error`)"
      schema:
        type: array
        items:
          type: string
        default: [ debug, info, warn, error ]
      x-oapi-codegen-extra-tags:
        default: '[\" debug\",\" info\",\" warn\",\" error\" ]'
    LogLevelWeights:
      name: logLevelWeights
      in: query
      description: "Log level weights (default: `1,5,3,2`)"
      schema:
        type: array
        items:
          type: number
        default: [ 1, 5, 3, 2 ]
      x-oapi-codegen-extra-tags:
        default: "[1, 5, 3, 2]"
    StreamInterval:
      name: interval
      in: query
      description: "Interval in milliseconds between streamed responses (min: 0; max: 5000)"
      schema:
        type: integer
        minimum: 0
        maximum: 5000
        default: 250
      x-oapi-codegen-extra-tags:
        validate: gt=0,lte=5000
        default: "250"
    Count:
      name: count
      in: query
      description: "Number of entries to return (min: 1; max: 10000)"
      schema:
        type: integer
        minimum: 1
        maximum: 10000
        default: 10
      x-oapi-codegen-extra-tags:
        validate: gt=1,lte=10000
        default: "10"
tags:
  - name: Meta
    description: "Endpoints providing meta functionality."
  - name: Return Request Data
    description: "Endpoints returning the received request data."
  - name: Status Codes
    description: "Endpoints to test various HTTP status codes."
  - name: JSON
    description: "Endpoints returning JSON data."
  - name: Stream
    description: "Endpoints returning streaming data."
