An OpenAPI specification is a descriptive YAML contract for an HTTP API. In a contract-first approach, define an endpoint in the contract, then use Maven to generate Java code for it. section 10.3.3
A shared API contract can help teams:
- Keep API structure and standards consistent across a project. section 10.3.3
- Share endpoint descriptions across teams and technologies, and generate API documentation automatically. 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 example describes a POST endpoint, its request body, response, and PaymentDetails schema. section 10.3.3













