Getting Started with OpenAPI
Command Line Setup
The quickest approach to getting started is through the command line.
Download the standalone Jar.
https://github.com/znsio/specmatic/releases/download/0.44.0/specmatic.jar
Mac / Linux
alias specmatic='java -jar <basedir>/specmatic.jar'
Windows
Create a batch file with below content.
java -jar <basedir>/specmatic.jar %*
The %* portion tells the batch script to pass all of the parameters it receives to the new command.
Sample OpenAPI spec to get you started
Create a file named “products.yaml” with below contents. This is a fairly simple API spec with a GET and POST operation to get a product by id and create a new Product. You can import it into Postman as a Collection or copy paste the contents and view it editor.swagger.io.
openapi: 3.0.0
info:
title: Order API
version: '1.0'
servers:
- url: 'http://localhost:3000'
paths:
'/products/{id}':
parameters:
- schema:
type: number
name: id
in: path
required: true
get:
summary: Fetch product details
tags: []
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Product'
'404':
description: Not Found
/products:
post:
summary: Add new product
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/ProductId'
parameters:
- schema:
type: string
in: header
name: Authenticate
required: true
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ProductDetails'
components:
schemas:
ProductDetails:
title: Product Details
type: object
properties:
name:
type: string
type:
$ref: '#/components/schemas/ProductType'
inventory:
type: integer
required:
- name
- type
- inventory
ProductType:
type: string
title: Product Type
enum:
- book
- food
- gadget
- other
ProductId:
title: Product Id
type: object
properties:
id:
type: integer
required:
- id
Product:
title: Product
allOf:
- $ref: '#/components/schemas/ProductId'
- $ref: '#/components/schemas/ProductDetails'
Stub mode - Smart Service Virtualisation
Now you can run a stub server by running below command.
$ java -jar <path to specmatic jar>/specmatic.jar stub products.yaml
Loading products.yaml
Stub server is running on http://0.0.0.0:9000. Ctrl + C to stop.
You should now be able to see the stub server running on your local machine on port 9000 as shown above.
Run below curl command or hit the URL http://localhost:9000/products/1 to get an auto-generated stub response.
$ curl -X GET http://localhost:9000/products/1
{
"id": 408,
"name": "DKKJF",
"type": "book",
"inventory": 321
}
Now you can try the POST call. Experiment with below call by removing headers, changing data types etc. in the request and observe the errors.
$ curl -X POST --header "Content-Type: application/json" --header "Authenticate: token" --header "Accept: application/json" -d '{"name": "transmogrifier", "type": "gadget", "inventory": 93412555}' http://localhost:9000/products
{
"id": 478
}
You can also import the “products.yaml” into Postman as a Collection. Just remember to set base URL to host and port where Specmatic is running.
Static Stub Responses
In certain use cases it may be necessary to set up the Specmatic Stub server to return a specific response given a combination of request parameters.
- Create a folder with name “products_data” in the same location where the “products.yaml” file exists.
- Specmatic will be able to associate this folder with the spec file based on naming convention and load any stub files within that folder.
- Create a json file below content inside “products_data”. For example: “air-jordans.json”
{ "http-request": { "path": "/products/1", "method": "GET" }, "http-response": { "status": 200, "body": { "id": 1, "name": "Air Jordan Sports Sneakers", "type": "gadget", "inventory": 6 }, "status-text": "OK", "headers": { "Content-Type": "application/json" } } }
- Start Specmatic Stub Server and you will notice the stub file being read.
$ java -jar <path to specmatic jar>/specmatic.jar stub products.yaml Loading products.yaml Loading stub expectations from <path to openapi spec>/products_data Reading the following stub files: <path to openapi spec>/air-jordans.json Stub server is running on http://0.0.0.0:9000. Ctrl + C to stop.
- Now when you run a curl to get Product Id 1, you will always get the response that you have added in JSON file. Any Product Id other than 1 will continue to return auto-generated response.
$ curl -X GET http://localhost:9000/products/1 { "id": 1, "name": "Air Jordan Sports Sneakers", "type": "gadget", "inventory": 6 }
- Update the “air-jordans.json” file and change type attribute value from “gadget” to “shoe”.
- Now if you start the Specmatic Server (if it is already running just observe the shell) you will notice that “air-jordans.json” will throw an error because it is not as the “products.yaml” (“type” enum does not have “shoe”).
$ java -jar <path to specmatic jar>/specmatic.jar stub products.yaml Loading products.yaml Loading stub expectations from <path to openapi spec>/products_data Reading the following stub files: <path to openapi spec>/products_data/air-jordans.json <path to openapi spec>/products_data/air-jordans.json didn\'t match products.yaml In scenario "Open API - Operation Summary: Fetch product details. Response: OK" >> RESPONSE.BODY.type Expected ("book" or "food" or "gadget" or "other"), Actual was string: "shoe" Stub server is running on http://0.0.0.0:9000. Ctrl + C to stop.
- By verifying stub jsons against their corresponding OpenAPI specs Specmatic makes sure the spec and stub data remain in sync
Error Response
- Create a json file below content inside “products_data”. For example: “404.json”
{ "http-request": { "path": "/products/0", "method": "GET" }, "http-response": { "status": 404, "status-text": "NOT FOUND", "headers": { "Content-Type": "application/json" } } }
- Start Specmatic Stub Server and you will notice both stub files being read.
$ java -jar <path to specmatic jar>/specmatic.jar stub products.yaml --verbose Loading products.yaml Parsing contract file products.yaml, absolute path <path to openapi spec>/products.yaml Loading stub expectations from <path to openapi spec>/products_data Reading the following stub files: <path to openapi spec>/products_data/air-jordans.json <path to openapi spec>/products_data/404.json Stub server is running on http://0.0.0.0:9000. Ctrl + C to stop.
- Now when you run a curl to get Product Id 0, you will always get the 404 NOT FOUND response that you have added in JSON file.
- You can only stub the errors that are already in OpenAPI spec. Example: Specmatic will not allow you to stub a 403 response until you add it to the “products.yaml” as a possible response.