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: stubs
    description: Stubs storage management
  - name: services
    description: Services reflection
  - name: dashboard
    description: Dashboard
  - name: healthcheck
    description: Healthcheck
  - name: descriptors
    description: Protocol Buffer descriptors (FileDescriptorSet)
  - name: mcp
    description: Model Context Protocol (MCP) integration
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

  # 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

  # mcp
  /mcp:
    get:
      tags:
        - mcp
      summary: MCP transport metadata
      description: Returns MCP server metadata, supported protocol versions and transport details.
      operationId: mcpInfo
      responses:
        '200':
          description: MCP metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpInfoResponse'
        '500':
          description: Internal Server Error
    post:
      tags:
        - mcp
      summary: MCP JSON-RPC endpoint
      description: Accepts MCP JSON-RPC requests (`initialize`, `ping`, `tools/list`, `tools/call`) and returns JSON-RPC responses.
      operationId: mcpMessage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/McpRequest'
      responses:
        '200':
          description: MCP JSON-RPC response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpResponse'
        '400':
          description: Invalid JSON request
        '500':
          description: Internal Server Error

  # internal
  /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}:
    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
      operationId: listStubs
      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/{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'

  # history & verify
  /history:
    get:
      tags:
        - history
      summary: Get call history
      description: Returns recorded gRPC calls (when history is enabled)
      operationId: listHistory
      responses:
        '200':
          description: List of recorded calls
          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'

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
    McpTransport:
      type: object
      required:
        - path
        - methods
      properties:
        path:
          type: string
          example: /api/mcp
        methods:
          type: array
          items:
            type: string
    McpTool:
      type: object
      required:
        - name
        - description
        - inputSchema
      properties:
        name:
          type: string
        description:
          type: string
        inputSchema:
          type: object
          additionalProperties: true
          x-go-type: map[string]any
          x-go-type-skip-optional-pointer: true
    McpInfoResponse:
      type: object
      required:
        - protocolVersion
        - serverName
        - serverVersion
        - transport
        - methods
        - tools
      properties:
        protocolVersion:
          type: string
        serverName:
          type: string
        serverVersion:
          type: string
        transport:
          $ref: '#/components/schemas/McpTransport'
        methods:
          type: array
          items:
            type: string
        tools:
          type: array
          items:
            $ref: '#/components/schemas/McpTool'
      example:
        protocolVersion: "2024-11-05"
        serverName: gripmock
        serverVersion: 3.7.1
        transport:
          path: /api/mcp
          methods: [GET, POST]
        methods: [initialize, ping, tools/list, tools/call]
        tools:
          - name: stubs.upsert
            description: Create or update one or many stubs
            inputSchema:
              type: object
              required: [stubs]
              properties:
                stubs:
                  oneOf:
                    - type: object
                    - type: array
          - name: schema.stub
            description: Return JSON Schema URL for stubs payload
            inputSchema:
              type: object
    McpRequest:
      type: object
      required:
        - jsonrpc
        - method
      properties:
        jsonrpc:
          type: string
          example: "2.0"
        id:
          $ref: '#/components/schemas/McpID'
        method:
          type: string
        params:
          type: object
          additionalProperties: true
          x-go-type: map[string]any
          x-go-type-skip-optional-pointer: true
      example:
        jsonrpc: "2.0"
        id: 10
        method: tools/call
        params:
          name: stubs.upsert
          arguments:
            stubs:
              service: unitconverter.v1.UnitConversionService
              method: ConvertWeight
              input:
                equals:
                  value: 1
                  from_unit: POUNDS
                  to_unit: KILOGRAMS
              output:
                data:
                  converted_value: 0.453592
    McpError:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: integer
        message:
          type: string
        data:
          type: object
          additionalProperties: true
          x-go-type: map[string]any
          x-go-type-skip-optional-pointer: true
    McpResponse:
      type: object
      required:
        - jsonrpc
      properties:
        jsonrpc:
          type: string
          example: "2.0"
        id:
          $ref: '#/components/schemas/McpID'
        result:
          type: object
          additionalProperties: true
          x-go-type: map[string]any
          x-go-type-skip-optional-pointer: true
        error:
          $ref: '#/components/schemas/McpError'
      example:
        jsonrpc: "2.0"
        id: 10
        result:
          content:
            - type: text
              text: OK
          structuredContent:
            ids:
              - fc800277-9bbb-4e0b-988e-4cf01b525085
          isError: false
    McpID:
      nullable: true
      oneOf:
        - type: string
        - type: integer
    # 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
      properties:
        id:
          type: string
          x-omitzero: false
        name:
          type: string
          x-omitzero: false
    # stubs
    ID:
      type: string
      format: 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
        request:
          type: object
          additionalProperties: true
        response:
          type: object
          additionalProperties: true
        error:
          type: string
        stubId:
          type: string
        timestamp:
          type: string
          format: date-time
    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
    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
        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
    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
    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
    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
    StubOutput:
      type: object
      properties:
        data:
          type: object
          additionalProperties: true
          x-go-type-skip-optional-pointer: true
        stream:
          type: array
          items:
            type: object
            additionalProperties: true
          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