A design-first, or contract-first, approach defines a REST API in a specification before implementing its endpoints. The contract describes details such as HTTP methods, paths, request bodies, and responses; tools can generate part of the endpoint implementation from it. section 10.3.3
Starting with a shared contract can help teams:
- Keep APIs consistent by generating implementations from the same structure and standards. section 10.3.3
- Share endpoint expectations across backend and frontend teams without relying on Java code. section 10.3.3
- Generate API documentation from the contract. section 10.3.3
openapi: 3.0.3
info:
title: Payment API
description: API for processing payments
version: 1.0.0
paths:
/payment: #A
post: #B
summary: Make a payment
operationId: makePayment #C
requestBody: #D
description: Payment details
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentDetails'
responses: #E
'200':
description: Payment processed successfully
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentDetails'
components:
schemas:
PaymentDetails: #F
type: object
properties:
amount:
type: number
format: double
example: 100.50The Payment API contract describes a POST /payment endpoint, its request body, response, and PaymentDetails schema. section 10.3.3


