Microcks test API

openapi: 3.0.2
info:
  title: Microcks API v1.14 config test API
  version: 1.14.0
  description: API offered by Microcks, the Kubernetes native tool for API and microservices mocking and testing (microcks.io)
  contact:
    name: Laurent Broudoux
    url: https://github.com/microcks
    email: laurent@microcks.io
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  x-logo:
    backgroundColor: '#ffffff'
    url: https://microcks.io/images/microcks-logo-blue.png
servers:
- url: http://microcks.example.com/api
  description: ''
security:
- jwt-bearer: []
tags:
- name: test
  description: Operations related to API and Services tests
paths:
  /tests:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TestRequest'
        required: true
      tags:
      - test
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestResult'
          description: Created TestResult (empty shell cause tests are executed asynchronously)
      security:
      - jwt-bearer:
        - user
      operationId: CreateTest
      summary: Create a new Test
  /tests/service/{serviceId}:
    parameters:
    - name: serviceId
      description: Unique identifier of Service to manage TestResults for
      schema:
        type: string
      in: path
      required: true
    get:
      tags:
      - test
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TestResult'
          description: List of TestResults for the Service having the requested id
      security:
      - jwt-bearer:
        - user
      operationId: GetTestResultsByService
      summary: Get TestResults by Service
  /tests/service/{serviceId}/count:
    parameters:
    - name: serviceId
      description: Unique identifier of Service to manage TestResults for
      schema:
        type: string
      in: path
      required: true
    get:
      tags:
      - test
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Counter'
          description: Number of TestResults for this Service in datastore
      security:
      - jwt-bearer:
        - user
      operationId: GetTestResultsByServiceCounter
      summary: Get the TestResults for Service counter
  /tests/{id}:
    parameters:
    - name: id
      description: Unique identifier of TestResult to manage
      schema:
        type: string
      in: path
      required: true
    get:
      tags:
      - test
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestResult'
          description: Requested TestResult
      security:
      - jwt-bearer:
        - user
      operationId: GetTestResult
      summary: Get TestResult
      description: ''
  /tests/{id}/messages/{testCaseId}:
    parameters:
    - name: id
      description: Unique identifier of TestResult to manage
      schema:
        type: string
      in: path
      required: true
    - name: testCaseId
      description: Unique identifier of TetsCaseResult to manage
      schema:
        type: string
      in: path
      required: true
    get:
      tags:
      - test
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RequestResponsePair'
          description: List of request and response messages for this TestCase
      security:
      - jwt-bearer:
        - user
      operationId: GetMessagesByTestCase
      summary: Get messages for TestCase
  /tests/{id}/testCaseResult:
    parameters:
    - name: id
      description: Unique identifier of TestResult to manage
      schema:
        type: string
      in: path
      required: true
    post:
      requestBody:
        description: TestCase return wrapper object
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TestCaseReturnDTO'
        required: true
      tags:
      - test
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestCaseResult'
          description: TestCaseResult is reported
      operationId: ReportTestCaseResult
      summary: Report and create a new TestCaseResult
      description: Report a TestCaseResult (typically used by a Test runner)
  /tests/{id}/events/{testCaseId}:
    parameters:
    - name: id
      description: Unique identifier of TestResult to manage
      schema:
        type: string
      in: path
      required: true
    - name: testCaseId
      description: Unique identifier of TetsCaseResult to manage
      schema:
        type: string
      in: path
      required: true
    get:
      tags:
      - test
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UnidirectionalEvent'
          description: List of event messages for this TestCase
      operationId: GetEventsByTestCase
      summary: Get events for TestCase
components:
  schemas:
    TestRequest:
      description: Test request is a minimalist wrapper for requesting the launch of a new test
      required:
      - serviceId
      - testEndpoint
      - runnerType
      - timeout
      properties:
        serviceId:
          description: Unique identifier of service to test
          type: string
        testEndpoint:
          description: Endpoint to test for this service
          type: string
        runnerType:
          $ref: '#/components/schemas/TestRunnerType'
          description: Runner used for this test
        timeout:
          format: int64
          description: The maximum time (in milliseconds) to wait for this test ends
          type: integer
        filteredOperations:
          description: A restriction on service operations to test
          type: array
          items:
            type: string
        secretName:
          description: The name of Secret to use for connecting the test endpoint
          type: string
        oAuth2Context:
          $ref: '#/components/schemas/OAuth2ClientContext'
          description: An OAuth2 context to use for retrieving an access token prior invoking the tested endpoint
        operationsHeaders:
          $ref: '#/components/schemas/OperationHeaders'
          description: This test operations headers override
    OAuth2ClientContext:
      description: Represents a volatile OAuth2 client context usually associated with a Test request
      required:
      - clientId
      - clientSecret
      - tokenUri
      - grantType
      type: object
      properties:
        clientId:
          description: Id for connecting to OAuth2 identity provider
          type: string
        clientSecret:
          format: password
          description: Secret for connecting to OAuth2 identity provider
          type: string
        tokenUri:
          description: URI for retrieving an access token from OAuth2 identity provider
          type: string
        username:
          description: Username in case you're using the Resource Owner Password flow
          type: string
        password:
          description: User password in case you're suing the Resource Owner password flow
          type: string
        refreshToken:
          description: Refresh token in case you're using the Refresh Token rotation flow
          type: string
        scopes:
          description: The OAuth scopes to have in claimed token (delimited by space, "openid" is applied by default)
          type: string
        grantType:
          description: The OAuth2 grant type to apply for retrieving the token
          enum:
          - PASSWORD
          - CLIENT_CREDENTIALS
          - REFRESH_TOKEN
          type: string
    Counter:
      description: A simple Counter type.
      type: object
      properties:
        counter:
          format: int32
          description: Number of items in a resource collection
          type: integer
      example: "{\n    \"counter\": 12\n}"
    EventMessage:
      description: A simple event message published or received in an asynchronous exchange
      type: object
      allOf:
      - required:
        - id
        - mediaType
        type: object
        properties:
          mediaType:
            description: Content type of message
            type: string
          dispatchCriteria:
            description: Dispatch criteria of this message (in case of a mock)
            type: string
      - $ref: '#/components/schemas/Message'
    Message:
      description: Common structure for Request, Response and EventMessage
      required:
      - name
      - operationId
      type: object
      properties:
        id:
          description: Unique identifier of this message
          type: string
        name:
          description: Unique distinct name of this message
          type: string
        content:
          description: Body content for this message
          type: string
        operationId:
          description: Identifier of Operation this message is associated to
          type: string
        testCaseId:
          description: Unique identifier of TestCase this message is attached (in case of a test)
          type: string
        headers:
          description: Headers for this message
          type: array
          items:
            $ref: '#/components/schemas/Header'
    RequestResponsePair:
      description: Request associated with corresponding Response
      type: object
      allOf:
      - required:
        - request
        - response
        type: object
        properties:
          request:
            $ref: '#/components/schemas/Request'
            description: The request part of the pair
          response:
            $ref: '#/components/schemas/Response'
            description: The Response part of the pair
      - $ref: '#/components/schemas/AbstractExchange'
    Request:
      description: A mock invocation or test request
      allOf:
      - type: object
        properties:
          responseId:
            description: Unique identifier of Response this Request is attached
            type: string
          queryParameters:
            description: Query parameters for this Request if any
            type: array
            items:
              $ref: '#/components/schemas/Parameter'
      - $ref: '#/components/schemas/Message'
    OperationHeaders:
      description: Specification of additional headers for a Service/API operations. Keys are operation name or "globals" (if header applies to all), values are Header objects DTO.
      type: object
      additionalProperties:
        type: array
        items:
          $ref: '#/components/schemas/HeaderDTO'
    OAuth2AuthorizedClient:
      description: OAuth2 authorized client that performed a test
      required:
      - grantType
      - principalName
      - tokenUri
      type: object
      properties:
        grantType:
          $ref: '#/components/schemas/OAuth2GrantType'
          description: OAuth2 authorization flow/grant type applied
        principalName:
          description: Name of authorized principal (clientId or username in the case of Password grant type)
          type: string
        tokenUri:
          description: Identity Provider URI used for token retrieval
          type: string
        scopes:
          description: Included scopes (separated using space)
          type: string
    Parameter:
      description: Companion objects for Request representing query parameter
      required:
      - name
      - value
      type: object
      properties:
        name:
          description: The name of the parameter
          type: string
        value:
          description: The value of this parameter
          type: string
    AbstractExchange:
      description: Abstract bean representing a Service or API Exchange.
      required:
      - type
      type: object
      properties:
        type:
          description: Discriminant type for identifying kind of exchange
          enum:
          - reqRespPair
          - unidirEvent
          type: string
    Header:
      description: Transport headers for both Requests and Responses
      required:
      - name
      - values
      type: object
      properties:
        name:
          description: Unique distinct name of this Header
          type: string
        values:
          description: Values for this Header
          type: array
          items:
            type: string
    Response:
      description: A mock invocation or test response
      allOf:
      - type: object
        properties:
          status:
            description: Status of this Response
            type: string
          mediaType:
            description: Content type of this Response
            type: string
          dispatchCriteria:
            description: Dispatch criteria of this Response (in case of a mock)
            type: string
          isFault:
            description: Whether this Response represents a Fault
            type: boolean
      - $ref: '#/components/schemas/Message'
    TestCaseResult:
      description: Companion objects for TestResult. Each TestCaseResult correspond to a particuliar service operation / action reference by the operationName field. TestCaseResults owns a collection of TestStepResults (one for every request associated to service operation / action).
      required:
      - success
      - elapsedTime
      - operationName
      properties:
        success:
          description: Flag telling if test case is a success
          type: boolean
        elapsedTime:
          description: Elapsed time in milliseconds since the test case beginning
          type: number
        operationName:
          description: Name of operation this test case is bound to
          type: string
        testStepResults:
          description: Test steps associated to this test case
          type: array
          items:
            $ref: '#/components/schemas/TestStepResult'
    TestStepResult:
      description: TestStepResult is an entity embedded within TestCaseResult. They are created for each request associated with an operation / action of a microservice.
      required:
      - success
      - elapsedTome
      properties:
        success:
          description: Flag telling if test case is a success
          type: boolean
        elapsedTime:
          description: Elapsed time in milliseconds since the test step beginning
          type: number
        requestName:
          description: Name of request this test step is bound to
          type: string
        message:
          description: Error message that may be associated to this test step
          type: string
        eventMessageName:
          description: Name of event this test step is bound to
          type: string
    TestCaseReturnDTO:
      required:
      - operationName
      properties:
        operationName:
          description: Name of related operation for this TestCase
          type: string
    TestResult:
      description: Represents the result of a Service or API test run by Microcks. Tests are related to a service and made of multiple test cases corresponding to each operations / actions composing service. Tests are run against a specific endpoint named testedEndpoint. It holds global markers telling if test still ran, is a success, how many times is has taken and so on ...
      required:
      - id
      - version
      - testNumber
      - testDate
      - testedEndpoint
      - serviceId
      - success
      - inProgress
      - runnerType
      properties:
        id:
          description: Unique identifier of TestResult
          type: string
        version:
          description: Revision number of this test
          type: number
        testNumber:
          description: Incremental number for tracking number of tests of a service
          type: number
        testDate:
          format: int64
          description: Timestamp of creation date of this service
          type: integer
        testedEndpoint:
          description: Endpoint used during test
          type: string
        serviceId:
          description: Unique identifier of service tested
          type: string
        elapsedTime:
          description: Elapsed time in milliseconds since test beginning
          type: number
        success:
          description: Flag telling if test is a success
          type: boolean
        inProgress:
          description: Flag telling is test is still in progress
          type: boolean
        runnerType:
          $ref: '#/components/schemas/TestRunnerType'
          description: Runner used for this test
        testCaseResults:
          description: TestCase results associated to this test
          type: array
          items:
            $ref: '#/components/schemas/TestCaseResult'
        secretRef:
          $ref: '#/components/schemas/SecretRef'
          description: The referrence of the Secret used for connecting to test endpoint
        operationHeaders:
          $ref: '#/components/schemas/OperationHeaders'
          description: This test operations headers override
        timeout:
          description: The maximum time (in milliseconds) to wait for this test ends
          type: integer
        authorizedClient:
          $ref: '#/components/schemas/OAuth2AuthorizedClient'
          description: The OAuth2 authorized client that performed the test
    TestRunnerType:
      description: Type of test strategy (different strategies are implemented by different runners)
      enum:
      - HTTP
      - SOAP_HTTP
      - SOAP_UI
      - POSTMAN
      - OPEN_API_SCHEMA
      - ASYNC_API_SCHEMA
      - GRPC_PROTOBUF
      - GRAPHQL_SCHEMA
      type: string
    SecretRef:
      description: Lightweight reference for an existing Secret
      required:
      - secretId
      - name
      properties:
        secretId:
          description: Unique identifier or referenced Secret
          type: string
        name:
          description: Distinct name of the referenced Secret
          type: string
      example: "{\n    \"secretId\": \"5be58fb51ed744d1b87481bd\",\n    \"name\": \"Gogs internal\"\n}"
    HeaderDTO:
      description: Data Transfert Object for headers of both Requests and Responses
      required:
      - name
      - values
      type: object
      properties:
        name:
          description: Unique distinct name of this Header
          type: string
        values:
          description: Values for this header (comma separated strings)
          type: string
    OAuth2GrantType:
      description: Enumeration for the different supported grants/flows of OAuth2
      enum:
      - PASSWORD
      - CLIENT_CREDENTIALS
      - REFRESH_TOKEN
      type: string
    UnidirectionalEvent:
      description: Representation of an unidirectional exchange as an event message
      type: object
      allOf:
      - required:
        - eventMessage
        type: object
        properties:
          eventMessage:
            $ref: '#/components/schemas/EventMessage'
            description: Asynchronous message for this unidirectional event
      - $ref: '#/components/schemas/AbstractExchange'
  securitySchemes:
    jwt-bearer:
      flows:
        clientCredentials:
          tokenUrl: https://keycloak.example.com/realms/microcks/protocol/openid-connect/token
          refreshUrl: https://keycloak.example.com/realms/microcks/protocol/openid-connect/token
          scopes:
            user: Simple authenticated user
            manager: Services & APIs content manager
            admin: Administrator of the Microcks instance
      type: oauth2
      description: JWT Bearer acquired using OAuth 2 Authentication flow or Direct Access Grant