openapi: 3.0.2
servers:
  - url: /api
security:
  - {}
info:
  version: 3.0.0
  title: GripMock API Schema
  description: Documentation and API specification GripMock.
  contact:
    name: Maksim Babichev
    url: https://github.com/bavix/gripmock-openapi
  license:
    name: MIT
    url: https://github.com/bavix/gripmock-openapi/blob/master/LICENSE
tags:
  - name: healthcheck
    description: Healthcheck
  - name: dashboard
    description: Dashboard and runtime telemetry
  - name: sessions
    description: Session management
  - name: services
    description: Services reflection
  - name: stubs
    description: Stubs storage and matching
  - name: history
    description: Recorded gRPC call history
  - name: verify
    description: Verify call count expectations
  - name: descriptors
    description: Protocol Buffer descriptors (FileDescriptorSet)
paths:
  # healthcheck
  /health/liveness:
    get:
      tags:
        - healthcheck
      summary: Liveness check
      description: This endpoint indicates that the service is alive and ready to handle requests
      operationId: liveness
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageOK'
        '400':
          description: Bad Request
        '500':
          description: Internal Server Error
  /health/readiness:
    get:
      tags:
        - healthcheck
      summary: Readiness check
      description: The test indicates readiness to receive traffic
      operationId: readiness
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageOK'
        '400':
          description: Bad Request
        '500':
          description: Internal Server Error

  # dashboard
  /dashboard:
    get:
      tags:
        - dashboard
      summary: Dashboard aggregate payload
      description: Returns combined dashboard counters, runtime metadata, and process state in one response.
      operationId: dashboard
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dashboard'
        '500':
          description: Internal Server Error
  /dashboard/overview:
    get:
      tags:
        - dashboard
      summary: Dashboard overview metrics
      description: Returns lightweight aggregate counters for admin UI dashboard.
      operationId: dashboardOverview
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DashboardOverview'
        '500':
          description: Internal Server Error
  /dashboard/info:
    get:
      tags:
        - dashboard
      summary: Dashboard runtime and build info
      description: Returns GripMock build metadata and current runtime process information.
      operationId: dashboardInfo
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DashboardInfo'
        '500':
          description: Internal Server Error

  # sessions
  /sessions:
    get:
      tags:
        - sessions
      summary: Session options
      description: Returns distinct non-empty session IDs available in current stubs.
      operationId: sessionsList
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sessions'
        '500':
          description: Internal Server Error

  # services reflection
  /services:
    get:
      tags:
        - services
      summary: Services
      description: List of registered services
      operationId: servicesList
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Service'
        '404':
          description: No services found
        '500':
          description: Internal Server Error
  /services/{serviceID}/methods:
    get:
      tags:
        - services
      summary: Service methods
      description: List of registered service methods
      operationId: serviceMethodsList
      parameters:
        - name: serviceID
          in: path
          description: ID of service
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Method'
        '400':
          description: Invalid service ID
        '404':
          description: Service not found
        '500':
          description: Internal Server Error
  /services/{serviceID}/methods/{methodID}:
    get:
      tags:
        - services
      summary: Service method details
      description: Returns exact metadata for one method (by short name or full method id).
      operationId: serviceMethodGet
      parameters:
        - name: serviceID
          in: path
          description: Full service name (e.g. helloworld.Greeter)
          required: true
          schema:
            type: string
        - name: methodID
          in: path
          description: Method short name (e.g. SayHello) or full id (e.g. helloworld.Greeter/SayHello)
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Method'
        '400':
          description: Invalid service or method id
        '404':
          description: Service or method not found
        '500':
          description: Internal Server Error
  /services/{serviceID}:
    get:
      tags:
        - services
      summary: Service details
      description: Returns exact metadata for one service including all methods and streaming capabilities.
      operationId: serviceGet
      parameters:
        - name: serviceID
          in: path
          description: Full service name (e.g. helloworld.Greeter)
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Service'
        '400':
          description: Invalid service ID
        '404':
          description: Service not found
        '500':
          description: Internal Server Error
    delete:
      tags:
        - services
      summary: Remove service
      description: Removes a service added via POST /descriptors. Services from startup (proto path) cannot be removed.
      operationId: deleteService
      parameters:
        - name: serviceID
          in: path
          description: Full service name (e.g. helloworld.Greeter)
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Service removed successfully
        '404':
          description: Service not found (not added via REST or already removed)
        '500':
          description: Internal Server Error

  # stubs
  /stubs/used:
    get:
      tags:
        - stubs
      summary: Getting a list of used stubs
      description: The list is needed to quickly find used stubs
      operationId: listUsedStubs
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StubList'
        '404':
          description: No used stubs found
        '500':
          description: Internal Server Error
  /stubs/unused:
    get:
      tags:
        - stubs
      summary: Getting a list of unused stubs
      description: The list is needed to quickly find unused stubs
      operationId: listUnusedStubs
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StubList'
        '404':
          description: No unused stubs found
        '500':
          description: Internal Server Error
  /stubs:
    get:
      tags:
        - stubs
      summary: Getting a list of stubs
      description: The list of stubs is required to view all added stubs. Use source query param to filter by source.
      operationId: listStubs
      parameters:
        - name: source
          in: query
          description: Filter by source (file, rest, mcp, proxy)
          required: false
          schema:
            type: string
        - name: service
          in: query
          description: Filter by service name (exact match)
          required: false
          schema:
            type: string
        - name: method
          in: query
          description: Filter by method name (exact match)
          required: false
          schema:
            type: string
        - name: session
          in: query
          description: Filter by session ID (empty means global stubs)
          required: false
          schema:
            type: string
        - name: q
          in: query
          description: Case-insensitive substring search over service, method and stub ID
          required: false
          schema:
            type: string
        - name: matcher
          in: query
          description: >-
            Filter by matcher kind(s) present on the stub input. Comma-separated
            for OR semantics (e.g. "glob,anyOf"). Valid kinds: equals, contains,
            matches, glob, anyOf.
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: Maximum number of returned stubs
          required: false
          schema:
            type: integer
            minimum: 1
        - name: offset
          in: query
          description: Number of stubs to skip before returning results
          required: false
          schema:
            type: integer
            minimum: 0
        - name: sort
          in: query
          description: Sort order for result list
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StubList'
        '404':
          description: No stubs found
        '500':
          description: Internal Server Error
    post:
      tags:
        - stubs
      summary: Add a new stub to the store
      description: Creates a new stub or multiple stubs and adds them to the storage
      operationId: addStub
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ListID'
        '400':
          description: Invalid stub data
        '422':
          description: Validation error
        '500':
          description: Internal Server Error
      requestBody:
        description: Create a new stub in the store
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/StubList'
                - $ref: '#/components/schemas/Stub'
    delete:
      tags:
        - stubs
      summary: Remove all stubs
      description: Completely clears the stub storage
      operationId: purgeStubs
      responses:
        '204':
          description: Successful operation
        '400':
          description: Bad Request
        '500':
          description: Internal Server Error
  /stubs/batchDelete:
    post:
      tags:
        - stubs
      summary: Deletes a batch of stubs by IDs
      description: Takes IDs as input and deletes them
      operationId: batchStubsDelete
      responses:
        '204':
          description: Successful operation
        '400':
          description: Invalid IDs provided
        '404':
          description: Some stubs not found
        '500':
          description: Internal Server Error
      requestBody:
        description: Delete stubs by their IDs
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListID'
  /stubs/validate:
    post:
      tags:
        - stubs
      summary: Validate a stub payload without persisting
      description: Validates one or more stubs and returns them normalized without adding to storage
      operationId: validateStub
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/StubList'
        '400':
          description: Invalid stub data
        '422':
          description: Validation error
        '500':
          description: Internal Server Error
      requestBody:
        description: Stub payload to validate
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/StubList'
                - $ref: '#/components/schemas/Stub'
  /stubs/{uuid}:
    get:
      tags:
        - stubs
      summary: Get Stub by ID
      description: Searches for Stub by ID
      operationId: findByID
      parameters:
        - name: uuid
          in: path
          description: ID of stub
          required: true
          schema:
            $ref: '#/components/schemas/ID'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Stub'
        '400':
          description: Invalid UUID format
        '404':
          description: Stub not found
        '500':
          description: Internal Server Error
    delete:
      tags:
        - stubs
      summary: Deletes stub by ID
      description: The method removes the stub by ID
      operationId: deleteStubByID
      parameters:
        - name: uuid
          in: path
          description: ID of stub
          required: true
          schema:
            $ref: '#/components/schemas/ID'
      responses:
        '204':
          description: successful operation
        '400':
          description: Invalid UUID format
        '404':
          description: Stub not found
        '500':
          description: Internal Server Error
  /stubs/search:
    post:
      tags:
        - stubs
      summary: Stub storage search
      description: Performs a search for a stub by the given conditions
      operationId: searchStubs
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Invalid search criteria
        '422':
          description: Validation error
        '500':
          description: Internal Server Error
      requestBody:
        description: Search criteria including service, method, headers and data to match against stubs
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
  /stubs/inspect:
    post:
      tags:
        - stubs
      summary: Inspect stub matching decision path
      description: Returns detailed matching stages/candidates for a query without consuming stub times.
      operationId: inspectStubs
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InspectReport'
        '400':
          description: Invalid inspect criteria
        '422':
          description: Validation error
        '500':
          description: Internal Server Error
      requestBody:
        description: Inspect criteria including service, method, optional headers/session and input messages
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InspectRequest'

  # history & verify
  /history:
    get:
      tags:
        - history
      summary: Get call history
      description: Returns recorded gRPC calls (when history is enabled)
      operationId: listHistory
      parameters:
        - name: limit
          in: query
          required: false
          description: Return at most N most-recent records
          schema:
            type: integer
            minimum: 0
        - name: offset
          in: query
          required: false
          description: Skip the N newest records (page backward through older calls)
          schema:
            type: integer
            minimum: 0
        - name: service
          in: query
          required: false
          schema:
            type: string
        - name: method
          in: query
          required: false
          schema:
            type: string
        - name: error
          in: query
          required: false
          description: When true, return only calls that ended with a gRPC error
          schema:
            type: boolean
      responses:
        '200':
          description: List of recorded calls
          headers:
            X-Total-Count:
              description: Total number of records before pagination
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HistoryList'
        '500':
          description: Internal Server Error
  /verify:
    post:
      tags:
        - verify
      summary: Verify call counts
      description: Asserts that a method was called a specified number of times
      operationId: verifyCalls
      responses:
        '200':
          description: Verification passed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageOK'
        '400':
          description: Verification failed (wrong call count)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyError'
        '500':
          description: Internal Server Error
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyRequest'

  # descriptors
  /descriptors:
    get:
      tags:
        - descriptors
      summary: List service IDs from REST-added descriptors
      description: Returns service IDs (e.g. helloworld.Greeter) added via POST /descriptors. Use DELETE /services/{serviceID} to remove.
      operationId: listDescriptors
      responses:
        '200':
          description: List of removable service IDs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DescriptorServiceIDs'
        '500':
          description: Internal Server Error
    post:
      tags:
        - descriptors
      summary: Upload FileDescriptorSet
      description: Accepts binary Protocol Buffers FileDescriptorSet. Registers descriptors for dynamic service discovery. Returns service IDs for later removal via DELETE /services/{serviceID}.
      operationId: addDescriptors
      requestBody:
        required: true
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        '200':
          description: Descriptors registered successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddDescriptorsResponse'
        '400':
          description: Invalid or empty FileDescriptorSet
        '500':
          description: Internal Server Error

components:
  schemas:
    # health
    MessageOK:
      type: object
      required:
        - message
        - time
      properties:
        message:
          type: string
          x-omitzero: false
        time:
          type: string
          format: date-time
          x-omitzero: false
    AddDescriptorsResponse:
      type: object
      required:
        - message
        - time
        - serviceIDs
      properties:
        message:
          type: string
          x-omitzero: false
        time:
          type: string
          format: date-time
          x-omitzero: false
        serviceIDs:
          type: array
          items:
            type: string
          description: Service IDs (e.g. helloworld.Greeter) registered. Use DELETE /services/{serviceID} to remove.
    DescriptorServiceIDs:
      type: object
      required:
        - serviceIDs
      properties:
        serviceIDs:
          type: array
          items:
            type: string
          description: Service IDs added via POST /descriptors
    # services
    Service:
      type: object
      required:
        - id
        - package
        - name
        - methods
      properties:
        id:
          type: string
          x-omitzero: false
        package:
          type: string
          x-omitzero: false
        name:
          type: string
          x-omitzero: false
        methods:
          type: array
          items:
            $ref: '#/components/schemas/Method'
          x-omitzero: false
    Method:
      type: object
      required:
        - id
        - name
        - methodType
      properties:
        id:
          type: string
          x-omitzero: false
        name:
          type: string
          x-omitzero: false
        methodType:
          type: string
          description: gRPC method interaction type
          enum:
            - unary
            - client_streaming
            - server_streaming
            - bidi_streaming
          x-omitzero: false
        requestType:
          type: string
          description: Fully-qualified protobuf request message type
        responseType:
          type: string
          description: Fully-qualified protobuf response message type
        requestSchema:
          $ref: '#/components/schemas/ProtoMessageSchema'
        responseSchema:
          $ref: '#/components/schemas/ProtoMessageSchema'
        clientStreaming:
          type: boolean
          description: Indicates client-side streaming method
          x-go-type-skip-optional-pointer: true
        serverStreaming:
          type: boolean
          description: Indicates server-side streaming method
          x-go-type-skip-optional-pointer: true
    ProtoMessageSchema:
      type: object
      required:
        - typeName
        - fields
      properties:
        typeName:
          type: string
          description: Fully-qualified protobuf message type name
        recursiveRef:
          type: boolean
          description: True when schema expansion stopped due to recursive reference
          x-go-type-skip-optional-pointer: true
        fields:
          type: array
          items:
            $ref: '#/components/schemas/ProtoFieldSchema'
    ProtoFieldSchema:
      type: object
      required:
        - name
        - jsonName
        - number
        - kind
        - cardinality
      properties:
        name:
          type: string
        jsonName:
          type: string
        number:
          type: integer
          minimum: 1
        kind:
          type: string
        cardinality:
          type: string
          enum:
            - optional
            - required
            - repeated
        typeName:
          type: string
          description: Referenced protobuf type for message/enum fields
        oneof:
          type: string
          description: Oneof group name if field belongs to oneof
        enumValues:
          type: array
          items:
            type: string
        map:
          type: boolean
          x-go-type-skip-optional-pointer: true
        mapKeyKind:
          type: string
        mapValueKind:
          type: string
        mapValueTypeName:
          type: string
        message:
          $ref: '#/components/schemas/ProtoMessageSchema'
        mapValueMessage:
          $ref: '#/components/schemas/ProtoMessageSchema'
    # stubs
    ID:
      type: string
      format: uuid
      x-go-type: uuid.UUID
      x-go-type-import:
        name: uuid
        path: github.com/google/uuid
      example: 51c50050-ec27-4dae-a583-a32ca71a1dd5
      x-omitzero: false
    ListID:
      type: array
      items:
        $ref: '#/components/schemas/ID'
      x-omitzero: false
    StubList:
      type: array
      items:
        $ref: '#/components/schemas/Stub'
      x-omitzero: false
    SearchRequest:
      type: object
      required:
        - service
        - method
        - data
      properties:
        id:
          $ref: '#/components/schemas/ID'
        service:
          type: string
          example: Gripmock
          x-omitzero: false
        method:
          type: string
          example: SayHello
          x-omitzero: false
        headers:
          type: object
          additionalProperties:
            type: string
          x-go-type-skip-optional-pointer: true
        data:
          type: object
          x-go-type: interface{}
          additionalProperties: true
          x-omitzero: false
    SearchResponse:
      type: object
      required:
        - data
        - error
      properties:
        headers:
          type: object
          additionalProperties:
            type: string
          x-go-type-skip-optional-pointer: true
        data:
          type: object
          x-go-type: interface{}
          additionalProperties: true
          x-omitzero: false
        error:
          type: string
          example: Message not found
          x-omitzero: false
        code:
          type: integer
          format: uint32
          x-go-type: codes.Code
          x-go-type-import:
            name: codes
            path: google.golang.org/grpc/codes
          example: 3
          x-go-type-skip-optional-pointer: true
    CallRecord:
      type: object
      properties:
        service:
          type: string
        method:
          type: string
        session:
          type: string
          description: Session ID (empty = global)
        stubId:
          type: string
          format: uuid
          x-go-type: uuid.UUID
          x-go-type-import:
            name: uuid
            path: github.com/google/uuid
          description: Stub identifier
        timestamp:
          type: string
          format: date-time
        request:
          type: object
          additionalProperties: true
          description: "Deprecated: use requests for streaming calls"
          deprecated: true
        requests:
          type: array
          description: Request messages for streaming calls (client stream, bidi stream)
          items:
            type: object
            additionalProperties: true
        response:
          type: object
          additionalProperties: true
          description: "Deprecated: use responses for streaming calls"
          deprecated: true
        responses:
          type: array
          description: Response messages for streaming calls (server stream, bidi stream)
          items:
            type: object
            additionalProperties: true
        responseHeaders:
          type: object
          description: Normalized response metadata (header+trailer) the call answered with
          additionalProperties:
            type: string
          x-go-type-skip-optional-pointer: true
        code:
          type: integer
          description: gRPC status code (e.g., 0 for OK, 5 for NotFound)
        error:
          type: string
        elapsedMs:
          type: integer
          format: int64
          description: Handler duration in milliseconds
    HistoryList:
      type: array
      items:
        $ref: '#/components/schemas/CallRecord'
    VerifyRequest:
      type: object
      required:
        - service
        - method
        - expectedCount
      properties:
        service:
          type: string
        method:
          type: string
        expectedCount:
          type: integer
          minimum: 0
    VerifyError:
      type: object
      properties:
        message:
          type: string
        expected:
          type: integer
        actual:
          type: integer
    InspectRequest:
      type: object
      required:
        - service
        - method
      properties:
        id:
          $ref: '#/components/schemas/ID'
        service:
          type: string
        method:
          type: string
        session:
          type: string
        headers:
          type: object
          additionalProperties: true
          x-go-type-skip-optional-pointer: true
        input:
          type: array
          items:
            type: object
            additionalProperties: true
          x-go-type-skip-optional-pointer: true
    InspectStage:
      type: object
      required:
        - name
        - before
        - after
        - removed
      properties:
        name:
          type: string
        before:
          type: integer
        after:
          type: integer
        removed:
          type: integer
    InspectCandidateEvent:
      type: object
      required:
        - stage
        - result
      properties:
        stage:
          type: string
        result:
          type: string
        reason:
          type: string
    InspectCandidate:
      type: object
      required:
        - id
        - service
        - method
        - session
        - priority
        - times
        - used
        - specificity
        - score
        - visibleBySession
        - withinTimes
        - headersMatched
        - inputMatched
        - matched
        - excludedBy
        - events
      properties:
        id:
          type: string
        service:
          type: string
        method:
          type: string
        session:
          type: string
        priority:
          type: integer
        times:
          type: integer
        used:
          type: integer
        specificity:
          type: integer
        score:
          type: number
          format: double
        visibleBySession:
          type: boolean
        withinTimes:
          type: boolean
        headersMatched:
          type: boolean
        inputMatched:
          type: boolean
        matched:
          type: boolean
        excludedBy:
          type: array
          items:
            type: string
        events:
          type: array
          items:
            $ref: '#/components/schemas/InspectCandidateEvent'
    InspectReport:
      type: object
      required:
        - service
        - method
        - session
        - matchedStubId
        - similarStubId
        - fallbackToMethod
        - error
        - stages
        - candidates
      properties:
        service:
          type: string
        method:
          type: string
        session:
          type: string
        matchedStubId:
          type: string
        similarStubId:
          type: string
        fallbackToMethod:
          type: boolean
        error:
          type: string
        stages:
          type: array
          items:
            $ref: '#/components/schemas/InspectStage'
        candidates:
          type: array
          items:
            $ref: '#/components/schemas/InspectCandidate'
    DashboardOverview:
      type: object
      required:
        - totalServices
        - totalStubs
        - usedStubs
        - unusedStubs
        - totalSessions
        - runtimeDescriptors
        - totalHistory
        - historyErrors
      properties:
        totalServices:
          type: integer
          minimum: 0
        totalStubs:
          type: integer
          minimum: 0
        usedStubs:
          type: integer
          minimum: 0
        unusedStubs:
          type: integer
          minimum: 0
        coveredMethods:
          type: integer
          minimum: 0
          description: Number of gRPC methods that have at least one stub
          x-go-type-skip-optional-pointer: true
        totalMethods:
          type: integer
          minimum: 0
          description: Total number of gRPC methods across all services
          x-go-type-skip-optional-pointer: true
        grpcAddr:
          type: string
          description: Native gRPC listen address
          x-go-type-skip-optional-pointer: true
        gatewayAddr:
          type: string
          description: ConnectRPC + gRPC-web listen address
          x-go-type-skip-optional-pointer: true
        httpAddr:
          type: string
          description: Admin REST API + UI listen address
          x-go-type-skip-optional-pointer: true
        totalSessions:
          type: integer
          minimum: 0
        runtimeDescriptors:
          type: integer
          minimum: 0
        totalHistory:
          type: integer
          minimum: 0
        historyErrors:
          type: integer
          minimum: 0
    Sessions:
      type: object
      required:
        - sessions
      properties:
        sessions:
          type: array
          items:
            type: string
    DashboardInfo:
      type: object
      required:
        - appName
        - version
        - goVersion
        - compiler
        - goos
        - goarch
        - numCPU
        - startedAt
        - uptimeSeconds
        - ready
        - historyEnabled
        - totalServices
        - totalStubs
        - totalSessions
        - runtimeDescriptors
      properties:
        appName:
          type: string
        version:
          type: string
        goVersion:
          type: string
        compiler:
          type: string
        goos:
          type: string
        goarch:
          type: string
        numCPU:
          type: integer
          minimum: 1
        startedAt:
          type: string
          format: date-time
        uptimeSeconds:
          type: integer
          minimum: 0
        ready:
          type: boolean
        historyEnabled:
          type: boolean
        totalServices:
          type: integer
          minimum: 0
        totalStubs:
          type: integer
          minimum: 0
        totalSessions:
          type: integer
          minimum: 0
        runtimeDescriptors:
          type: integer
          minimum: 0
    Dashboard:
      type: object
      required:
        - appName
        - version
        - goVersion
        - compiler
        - goos
        - goarch
        - numCPU
        - startedAt
        - uptimeSeconds
        - ready
        - historyEnabled
        - totalServices
        - totalStubs
        - usedStubs
        - unusedStubs
        - totalSessions
        - runtimeDescriptors
        - totalHistory
        - historyErrors
      properties:
        appName:
          type: string
        version:
          type: string
        goVersion:
          type: string
        compiler:
          type: string
        goos:
          type: string
        goarch:
          type: string
        numCPU:
          type: integer
          minimum: 1
        startedAt:
          type: string
          format: date-time
        uptimeSeconds:
          type: integer
          minimum: 0
        ready:
          type: boolean
        historyEnabled:
          type: boolean
        totalServices:
          type: integer
          minimum: 0
        totalStubs:
          type: integer
          minimum: 0
        usedStubs:
          type: integer
          minimum: 0
        unusedStubs:
          type: integer
          minimum: 0
        coveredMethods:
          type: integer
          minimum: 0
          description: Number of gRPC methods that have at least one stub
          x-go-type-skip-optional-pointer: true
        totalMethods:
          type: integer
          minimum: 0
          description: Total number of gRPC methods across all services
          x-go-type-skip-optional-pointer: true
        grpcAddr:
          type: string
          description: Native gRPC listen address
          x-go-type-skip-optional-pointer: true
        gatewayAddr:
          type: string
          description: ConnectRPC + gRPC-web listen address
          x-go-type-skip-optional-pointer: true
        httpAddr:
          type: string
          description: Admin REST API + UI listen address
          x-go-type-skip-optional-pointer: true
        totalSessions:
          type: integer
          minimum: 0
        runtimeDescriptors:
          type: integer
          minimum: 0
        totalHistory:
          type: integer
          minimum: 0
        historyErrors:
          type: integer
          minimum: 0
    Stub:
      type: object
      required:
        - service
        - method
        - input
        - output
      properties:
        id:
          $ref: '#/components/schemas/ID'
        service:
          type: string
          example: Gripmock
          x-omitzero: false
        method:
          type: string
          example: SayHello
          x-omitzero: false
        priority:
          type: integer
          default: 0
          description: Priority of the stub. Higher priority stubs are matched first.
          x-go-type-skip-optional-pointer: true
        used:
          type: boolean
          description: Response-only — whether the stub has matched at least once. Ignored on input.
          x-go-type-skip-optional-pointer: true
        headers:
          $ref: '#/components/schemas/StubHeaders'
        input:
          $ref: '#/components/schemas/StubInput'
          x-omitzero: false
        inputs:
          type: array
          description: Inputs to match against. If multiple inputs are provided, the stub will be matched if any of the inputs match.
          items:
            $ref: '#/components/schemas/StubInput'
          x-go-type-skip-optional-pointer: true
        output:
          $ref: '#/components/schemas/StubOutput'
          x-omitzero: false
        options:
          $ref: '#/components/schemas/StubOptions'
          x-omitzero: true
        effects:
          type: array
          description: Side effects applied after successful stub match
          items:
            $ref: '#/components/schemas/StubEffect'
          x-go-type-skip-optional-pointer: true
        source:
          type: string
          description: Source of the stub (file, rest, mcp, proxy)
          readOnly: true
          x-omitzero: true
    StubOptions:
      type: object
      description: Optional behavior settings for a stub
      properties:
        times:
          type: integer
          description: Max number of matches; 0 = unlimited
          minimum: 0
          default: 0
          x-go-type-skip-optional-pointer: true
    StubEffect:
      type: object
      required:
        - action
      properties:
        action:
          type: string
          enum: [upsert, delete]
        id:
          type: string
          description: Stub UUID for delete action
          x-go-type-skip-optional-pointer: true
        stub:
          type: object
          additionalProperties: true
          description: Stub payload for upsert action
          x-go-type-skip-optional-pointer: true
    StubInput:
      type: object
      properties:
        ignoreArrayOrder:
          type: boolean
          default: false
          x-go-type-skip-optional-pointer: true
        equals:
          type: object
          additionalProperties: true
          x-go-type-skip-optional-pointer: true
        contains:
          type: object
          additionalProperties: true
          x-go-type-skip-optional-pointer: true
        matches:
          type: object
          additionalProperties: true
          x-go-type-skip-optional-pointer: true
        anyOf:
          type: array
          description: Alternative input matchers (OR logic)
          items:
            $ref: '#/components/schemas/StubInputAnyOfElement'
          x-go-type-skip-optional-pointer: true
    StubInputAnyOfElement:
      type: object
      properties:
        ignoreArrayOrder:
          type: boolean
          default: false
          x-go-type-skip-optional-pointer: true
        equals:
          type: object
          additionalProperties: true
          x-go-type-skip-optional-pointer: true
        contains:
          type: object
          additionalProperties: true
          x-go-type-skip-optional-pointer: true
        matches:
          type: object
          additionalProperties: true
          x-go-type-skip-optional-pointer: true
    StubHeaders:
      type: object
      x-go-type-skip-optional-pointer: true
      properties:
        equals:
          type: object
          additionalProperties:
            type: string
          x-go-type-skip-optional-pointer: true
        contains:
          type: object
          additionalProperties:
            type: string
          x-go-type-skip-optional-pointer: true
        matches:
          type: object
          additionalProperties:
            type: string
          x-go-type-skip-optional-pointer: true
        anyOf:
          type: array
          description: Alternative header matchers (OR logic)
          items:
            $ref: '#/components/schemas/StubHeadersAnyOfElement'
          x-go-type-skip-optional-pointer: true
    StubHeadersAnyOfElement:
      type: object
      properties:
        equals:
          type: object
          additionalProperties:
            type: string
          x-go-type-skip-optional-pointer: true
        contains:
          type: object
          additionalProperties:
            type: string
          x-go-type-skip-optional-pointer: true
        matches:
          type: object
          additionalProperties:
            type: string
          x-go-type-skip-optional-pointer: true
    StubOutput:
      type: object
      properties:
        data:
          x-go-type-skip-optional-pointer: true
        stream:
          type: array
          items: {}
          x-go-type-skip-optional-pointer: true
        headers:
          type: object
          additionalProperties:
            type: string
          x-go-type-skip-optional-pointer: true
        error:
          type: string
          example: Message not found
          x-go-type-skip-optional-pointer: true
        code:
          type: integer
          format: uint32
          x-go-type: codes.Code
          x-go-type-import:
            name: codes
            path: google.golang.org/grpc/codes
          example: 3
          x-go-type-skip-optional-pointer: true
        details:
          type: array
          description: gRPC status details packed into google.protobuf.Any (each item must contain type URL in `type`)
          items:
            type: object
            required: [type]
            properties:
              type:
                type: string
                description: Full Any type URL (for example, type.googleapis.com/google.rpc.ErrorInfo)
            additionalProperties: true
          x-go-type-skip-optional-pointer: true
        delay:
          type: string
          x-go-type: gptypes.Duration
          x-go-type-import:
            name: gptypes
            path: github.com/bavix/gripmock/v3/internal/infra/types
          description: Delay before sending the response
          example: "1s"
          x-omitzero: true
          x-go-type-skip-optional-pointer: true