diff --git a/docs/contract_driven_development/includes/service-virtualization/messages-retrieve-api/messages-retrieve-api.yaml b/docs/contract_driven_development/includes/service-virtualization/messages-retrieve-api/messages-retrieve-api.yaml new file mode 100644 index 000000000..f3050ec2d --- /dev/null +++ b/docs/contract_driven_development/includes/service-virtualization/messages-retrieve-api/messages-retrieve-api.yaml @@ -0,0 +1,88 @@ +openapi: 3.0.3 + +info: + title: Messages Retrieve API + description: API to retrieve messages served by the mock server + version: 1.0.0 + +paths: + /_specmatic/messages: + get: + summary: Retrieve served messages + description: > + Returns the list of messages served by the mock server. + You can optionally pass one or more query parameters as filters in the form `key=value`, + where each filter is an equality check (`key == value`) against message + parameters: + - in: query + name: filter + required: false + schema: + type: string + description: > + Any query parameter can be used as a filter. + The parameter name represents a request/response pointers + Example: + /_specmatic/messages?REQUEST.METHOD=GET + /_specmatic/messages?RESPONSE.STATUS=200 + /_specmatic/messages?REQUEST.PARAMETERS.HEADER.Content-Type=application/json + explode: true + allowReserved: true + responses: + "200": + description: Retrieved list of served messages + content: + application/json: + schema: + $ref: "#/components/schemas/MessagesResponse" + +components: + schemas: + AnyValue: {} + + MessagesResponse: + description: List of served message + type: array + items: + $ref: "#/components/schemas/RequestResponseSchema" + + RequestResponseSchema: + type: object + properties: + http-request: + $ref: "#/components/schemas/RequestSchema" + http-response: + $ref: "#/components/schemas/ResponseSchema" + required: + - http-request + - http-response + + RequestSchema: + type: object + properties: + path: + type: string + method: + type: string + query: + type: object + additionalProperties: true + headers: + type: object + additionalProperties: true + body: + nullable: true + $ref: "#/components/schemas/AnyValue" + + ResponseSchema: + type: object + properties: + status: + type: integer + minimum: 0 + headers: + type: object + additionalProperties: true + body: + nullable: true + $ref: "#/components/schemas/AnyValue" diff --git a/docs/contract_driven_development/service_virtualization.mdx b/docs/contract_driven_development/service_virtualization.mdx index acb1c528f..c219c672d 100644 --- a/docs/contract_driven_development/service_virtualization.mdx +++ b/docs/contract_driven_development/service_virtualization.mdx @@ -1478,6 +1478,72 @@ Here's the OpenAPI specification describing the `/actuator/health` endpoint. +## Retrieving Messages Served By The Mock Server + +You can use the `/_specmatic/messages` endpoint to retrieve the list of all messages served by the mock server. This is useful for debugging, verifying interactions, and asserting that specific traffic actually hit the mock. + +### What can be filtered + +If you call the endpoint without any query parameters, it will return everything that the mock server has served so far. + +You can also apply one or more filters by passing query parameters in the form `key=value`, Each query parameter acts as an equality check, +A filter key is a path-like selector that points to a value inside the each message. + +#### REQUEST +- `REQUEST.PATH` (URL path) +- `REQUEST.METHOD` +- `REQUEST.PARAMETERS.PATH.` +- `REQUEST.PARAMETERS.QUERY.` +- `REQUEST.PARAMETERS.HEADER.` +- `REQUEST.BODY.` + +#### RESPONSE +- `RESPONSE.STATUS` +- `RESPONSE.HEADER.` +- `RESPONSE.BODY.` + +> Note: When the target is inside an array, use `[index]` Example: `RESPONSE.BODY[1].details[0][1].name` + +### Example `curl` Requests + +Fetch **ALL** served messages: + +```shell +curl -X GET http:///_specmatic/messages +``` + +Fetch only messages where the request method is `GET`: + +```shell +curl -G -X GET "http:///_specmatic/messages" --data-urlencode "REQUEST.METHOD=GET" +``` + +Fetch only messages where response status is `200`: + +```shell +curl -G -X GET "http:///_specmatic/messages" --data-urlencode "RESPONSE.STATUS=200" +``` + +Fetch only messages where a request header matches: + +```shell +curl -G -X GET "http:///_specmatic/messages" --data-urlencode "REQUEST.HEADER.Accept=application/json" +``` + +Fetch only messages where a nested response body field matches: + +```shell +curl -G -X GET "http:///_specmatic/messages" --data-urlencode "RESPONSE.BODY[1].details[0][1].name=John" +``` + +Provide multiple filters `(N query params)`. All filters apply together: + +```shell +curl -G -X GET "http:///_specmatic/messages" \ + --data-urlencode "REQUEST.METHOD=POST" \ + --data-urlencode "RESPONSE.STATUS=201" +``` + ## Specmatic Configuration with Base URL, Host, Port, and Path By default, Specmatic mock servers run on `http://0.0.0.0:9000`