When frontend and backend teams work in parallel, an OpenAPI specification gives both sides a shared, human-readable description of the HTTP API. It defines endpoints, request details, and response expectations, supporting frontend mocks and backend test scenarios. As implementation changes, contract tests can verify that the service still matches those expectations before deployment. section 12.1 section 1.4
An OpenAPI specification can describe:
- Available endpoints and operations, such as GET /movies or GET /movie/{id}. section 12.1
- Parameters, required fields, response status codes, content types, schemas, properties, and example values. section 1.4 section 12.1
- Documentation generated from provider code, which tools such as Dredd can execute against a running service. section 11.3.2
- A shared boundary for contract testing, while leaving infrastructure, database, and deployment-configuration failures to integration tests. section 12.1
Verifying an Express movies API
An Express provider documents GET /movies with a 200 response containing movie objects whose id and year are integers and whose name is a string. The provider exposes the generated specification at /swagger.json. A Dredd configuration points to that specification and the running endpoint; running Dredd tests the documented scenarios and writes a report. Publishing the specification and results enables comparison with consumer contracts. section 11.3.2
openapi: 3.0.3
info:
title: Contract Testing - OpenAPI 3.0
version: 1.0.0
tags:
- name: user
description: Operations about user
paths:
/user/{id}:
get:
summary: Get an existing user
operationId: getUser
parameters:
- name: id
in: path
description: Id of user to return
required: true
schema:
type: integer
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/User'
components:
schemas:
User:
type: object
properties:
id:
type: integer
format: int64
example: 10
firstName:
type: string
example: Marie
lastName:
type: string
example: Cruz
Use the compact YAML listing to inspect how an OpenAPI document combines metadata, paths, parameters, responses, schemas, and examples. section 1.4
