liveBook · Manning

OpenAPI specification

As explained in Spring Start Here, Second Edition

OpenAPI is a standard, machine-readable specification format for describing HTTP APIs, including their operations, inputs, and responses.

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.50

The payment API example describes a POST endpoint, its request body, response, and PaymentDetails schema. section 10.3.3

How Spring Start Here, Second Edition covers it

How deep it goes
Defines the contract-first workflow and shows an endpoint example, but defers detailed OpenAPI instruction.
Examples
Describes a payment endpoint with a POST operation, request body, response, and PaymentDetails schema.
What you can do after
Understand how a contract-first workflow can generate endpoint code and documentation from an API description.
How it connects
Connects API contracts with Maven, Java code generation, and API documentation.

Also explained in

Compare how 14 books explain OpenAPI specification →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Spring Start Here, Second Edition. The section links point to the parts of the book it draws on.