I wrote recently about OpenAPI-first development in general terms. This is the concrete version: the planning workflow we’re trialling on my team, and the example YAML that goes with it.
Where this came from#
The push came from our retro. The feedback was blunt about how little visibility anyone had into API planning: backend built endpoints against their own reading of the requirements, frontend discovered the response shapes after the fact, and the gaps surfaced at integration time — the most expensive possible moment. The proposal was to pull both sides into the planning phase and make the OpenAPI schema the thing everything hangs off.
The process#
Each week we pick two representatives, one backend and one frontend. Their job is to understand the sprint’s requirements and get the planning OpenAPI schema to match. They review the schema together, revise whatever doesn’t line up, and by the end both sides know exactly what’s being built — before anyone builds it.
Once the revisions settle, the schema gets committed to the repo, and CI/CD generates a mock API from the yaml. When the sprint wraps up, a fresh yaml is cut covering the next sprint’s API requirements, and the cycle repeats.
Tooling notes#
- For visualising the yaml, Swagger Editor does the job: upload the file and see it rendered as a proper Swagger document.
- This schema is a planning artefact only. Once the real API is deployed, the service should generate its own openapi.json, which you can download and feed back into the next round of planning.
- The CI/CD pipeline needs to accept a yaml and stand up a mock server from it. openapi-mock looks like a solid option for that.
Why bother#
Because the arguments move to the cheapest possible place. With a frontend and a backend engineer in the room while the schema is written, misunderstandings get caught before they become code. The API requirements are agreed once instead of renegotiated mid-sprint, the mock server means frontend starts immediately rather than waiting, and far fewer critical details slip through — they’d have to get past two pairs of eyes and a written contract.
None of this is revolutionary. It’s just planning made concrete enough that a machine can serve it back to you as a mock — which, it turns out, is about the level of concrete a plan needs to be.
Appendix A - yaml example#
openapi: 3.1.0
info:
title: PKY Sprint 3
description: |-
PKY Sprint 3 Development Schema
termsOfService:
contact:
email: jared@lynskey.co.nz
license:
name: None
url:
version: 1.0.11
externalDocs:
description:
url:
servers:
- url: https://api-mock.com/api/v3
tags:
- name: curation
description: PKY-1081 Curated Lists Feature
externalDocs:
description: Jira Epic
url: https://pickydev.atlassian.net/browse/PKY-1081
paths:
/curations:
get:
tags:
- curation
summary: Return the curations created by users
description: Returns a map of status codes to quantities
operationId: getCurations
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: object
additionalProperties:
type: integer
format: int32
security:
- api_key: []
/curations/{curationId}:
get:
tags:
- curation
summary: Find purchase order by ID
description: For valid response try integer IDs with value <= 5 or > 10. Other values will generate exceptions.
operationId: getOrderById
parameters:
- name: orderId
in: path
description: ID of order that needs to be fetched
required: true
schema:
type: integer
format: int64
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
application/xml:
schema:
$ref: '#/components/schemas/Order'
'400':
description: Invalid ID supplied
'404':
description: Order not found
delete:
tags:
- curation
summary: Delete purchase order by ID
description: For valid response try integer IDs with value < 1000. Anything above 1000 or nonintegers will generate API errors
operationId: deleteOrder
parameters:
- name: orderId
in: path
description: ID of the order that needs to be deleted
required: true
schema:
type: integer
format: int64
responses:
'400':
description: Invalid ID supplied
'404':
description: Order not found
components:
schemas:
Curation:
type: object
properties:
id:
type: integer
format: int64
examples: [10]
curationId:
type: integer
format: int64
examples: [198772]
quantity:
type: integer
format: int32
examples: [7]
status:
type: string
description: Order Status
examples: [approved]
enum:
- placed
- approved
- delivered
complete:
type: boolean
xml:
name: order
ApiResponse:
type: object
properties:
code:
type: integer
format: int32
type:
type: string
message:
type: string
xml:
name: '##default'
requestBodies:
Curation:
description: Curation object that needs to be added
content:
application/json:
schema:
$ref:
application/xml:
schema:
$ref:
securitySchemes:
petstore_auth:
type: oauth2
flows:
implicit:
authorizationUrl:
scopes:
write:curations: modify curations in your account
read:curations: read your curations
api_key:
type: apiKey
name: api_key
in: header