Skip to content

Commit

Permalink
adding examples as stub data in getting_started section
Browse files Browse the repository at this point in the history
  • Loading branch information
@harikrishnan83
harikrishnan83 committed Feb 6, 2024
1 parent e526627 commit 69a2c69
Showing 1 changed file with 83 additions and 21 deletions.
104 changes: 83 additions & 21 deletions getting_started.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -79,7 +79,11 @@ paths:
type: "string"
examples:
200_OKAY:
value: '{any}'
value:
id: 1
type: "Golden Retriever"
name: "Scooby"
status: "Adopted"
```
---
Expand Down Expand Up @@ -290,22 +294,80 @@ You should now be able to see the response that matches the schema defined in yo
}
```

The response contains auto-generated values that adhere to the data type defined in the contract. In above output petid "864" is generated by specmatic and will vary with every execution. If you would like to control the value that is being returned you can set up stub / canned responses.
The response contains auto-generated values that adhere to the data type defined in the contract. In above output petid "864" is generated by specmatic and will vary with every execution.

However for petId 1, it will always return below values.
```shell
{
"id": 1,
"name": "Scooby",
"type": "Golden Retriever",
"status": "Adopted"
}
```

This is because the example `200_OKAY`, which we earlier saw being used while running contract test, also servers a stub data when we run Specmatic stub.

With this we have effectively achived three goals in one go.
* Examples serve as reference for people referring to the API specification as documentation
* The same examples are used while contract tests to create the HTTP request
* And these examples also serve as stub data when we run Spemcatic stub command

#### Intelligent Service Virtualisation

Let us try a few experiments. Remove the `status` field in the `200_OKAY` response example in `service.yaml` (the very last line in that file) and run the stub command again.

```yaml
examples:
200_OKAY:
value:
id: 1
type: "Golden Retriever"
name: "Scooby"
status: "Adopted" # Remove this line
```

You should an output like below.

```bash
Loading /service.yaml
API Specification Summary: /service.yaml
OpenAPI Version: 3.0.1
API Paths: 1, API Operations: 1
[Example 200_OKAY]: Error from contract /service.yaml
In scenario "Should be able to get a pet by petId. Response: Should be able to get a pet by petId"
API: GET /pets/(petid:number) -> 200
>> RESPONSE.BODY.status
key named status in the spec was not found in the "200_OKAY" example
```

Specmatic rejects the expectation / canned response since it is not in line with the OpenAPI Specification.

#### Externalising stub responses

Please restore `service.yaml` to its [original state](/getting_started.html#api-specification)(by adding back the `status` field in the `200_OKAY` example) before proceeding with this section.

If you would like to add more stub responses, however you do not wish to bloat your specification with a lot of examples, we can also externalise the stub / canned responses to json files also.
* Create a folder named `service_data` in the same folder as your `service.yaml` file (`_data` suffix is a naming convention that tell Specmatic to look for canned responses in that directory)
* Create a json file with the name `scooby.json` and add below contents to it
* Create a json file with the name `togo.json` and add below contents to it

```json
{
"http-request": {
"path": "/pets/1",
"path": "/pets/2",
"method": "GET"
},
"http-response": {
"status": 200,
"body": {
"id": 1,
"name": "Scooby",
"type": "Golden Retriever",
"id": 2,
"name": "Togo",
"type": "Siberian Husky",
"status": "Adopted"
},
"status-text": "OK"
Expand All @@ -329,7 +391,7 @@ npx specmatic stub service.yaml
```shell
# Please note docker command here has to volume map the directory containing service.yaml
# to a directory within the container so that both service.yaml and folder service_data along
# with scooby.json are available to Specmatic docker container
# with togo.json are available to Specmatic docker container
docker run -v "/local-directory/:/specs" -p 9000:9000 znsio/specmatic stub "/specs/service.yaml"
```
{% endtab %}
Expand All @@ -340,34 +402,34 @@ This time you should see Specmatic load your canned response file also.
Loading service.yaml
Loading stub expectations from /<dir with service.yaml>/service_data
Reading the following stub files:
/<dir with service.yaml>/service_data/scooby.json
/<dir with service.yaml>/service_data/togo.json
Stub server is running on http://0.0.0.0:9000. Ctrl + C to stop.
```

And let us now run the curl command.
Once the stub server is running you can verify the API by accessing it through Postman, Chrome, Curl etc.

```shell
curl http://localhost:9000/pets/1
curl http://localhost:9000/pets/2
```

Specmatic will now return your canned response for petId 1. For any other petId it will continue to return generated values.
You should now be able to see the data pertaining to the `togo.json` file that you added.

```shell
{
"id": 1,
"name": "Scooby",
"type": "Golden Retriever",
"id": 2,
"name": "Togo",
"type": "Siberian Husky",
"status": "Adopted"
}
```

So what is so smart about Specmatic Smart Mocks.

Let us try a few experiments. Remove the `status` field within http-response body in `scooby.json` and run the stub command again. You should an output like below.
Specmatic validates this externalised stub JSON file `togo.json` against the `service.yaml`. Let us try this by removing the `status` field within http-response body in `togo.json` and run the stub command again. You should an output like below.
```shell
Loading service.yaml
Loading stub expectations from /<dir with service.yaml>/service_data
Reading the following stub files:
/<dir with service.yaml>/service_data/scooby.json
/<dir with service.yaml>/service_data/scooby.json didnt match service.yaml
/<dir with service.yaml>/service_data/togo.json
/<dir with service.yaml>/service_data/togo.json didnt match service.yaml
Error from contract service.yaml
In scenario Should be able to get a pet by petId. Response: Should be able to get a pet by petId
Expand All @@ -379,7 +441,7 @@ Loading service.yaml
Stub server is running on http://0.0.0.0:9000. Ctrl + C to stop.
```

Specmatic rejects the expectation / canned response since it is not in line with the OpenAPI Specification.
Specmatic again rejects the expectation / canned response since it is not in line with the OpenAPI Specification.

To know more about smart mocks please refer to below video demos
* [Video: Smart Mocks](https://youtu.be/U5Agz-mvYIU?t=750)
Expand Down

0 comments on commit 69a2c69

Please sign in to comment.