Complaints from Product Owners

Image for post
Image for post
Credit: ShotPrime Studio

“My team is not efficient and the velocity is lower than the other teams (squads).” “ I have no idea what the developers are doing and why things are going so slow.” “ I’m going to meet with them more frequently to check their progress each day.” “Things keep getting carried over to the next sprint and almost nothing is done in time.”

Complaints from Developers


We’ll be using the following setups for this walkthrough

  • Springboot
  • Kotlin
  • Maven
  • OpenApiTool
  • Swagger-Codegen
  • Java 8
  • Intellij

Project setup

Let’s setup the Springboot code base first at https://start.spring.io/

Image for post
Image for post

Download the generated project and load it into Intellij

Write your own YAML Contract

You can use SwaggerHub https://swagger.io/tools/swaggerhub/ to write the contract. The online editor provides intellisense and error checking. You can also see the contract UI real time as you construct the contract. For our demo we’ll write up a basic contract.

I’ll use the below yaml for this demo.

openapi: 3.0.0
servers:
# Added by API Auto Mocking Plugin
- description: SwaggerHub API Auto Mocking
url: https://virtserver.swaggerhub.com/Z9527/ZDaySample/1.0.0
info:
description: This is a simple API
version: "1.0.0"
title: Simple Inventory API
contact:
email: you@your-company.com
license:
name: Apache 2.0
url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
tags:
- name: admins
description: Secured Admin-only calls
- name: developers
description: Operations available to regular developers
paths:
/inventory:
get:
tags:
- developers
summary: searches inventory
operationId: searchInventory
description: |
By passing in the appropriate options, you can search for
available inventory in the system
parameters:
- in: query
name: searchString
description: pass an optional search string
required: false
schema:
type: string
- in: query
name: skip
description: number of records to skip for pagination
schema:
type: integer
format: int32
minimum: 0
- in: query
name: limit
description: maximum number of records to return
schema:
type: integer
format: int32
minimum: 0
maximum: 50
responses:
'200':
description: search results matching criteria
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/InventoryItem'
'400':
description: bad input parameter
post:
tags:
- admins
summary: adds an inventory item
operationId: addInventory
description: Adds an item to the system
responses:
'201':
description: item created
'400':
description: 'invalid input, object invalid'
'409':
description: an existing item already exists
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/InventoryItem'
description: Inventory item to add
components:
schemas:
InventoryItem:
type: object
required:
- id
- name
- manufacturer
- releaseDate
properties:
id:
type: string
format: uuid
example: d290f1ee-6c54-4b01-90e6-d701748f0851
name:
type: string
example: Widget Adapter
releaseDate:
type: string
format: date-time
example: '2016-08-29T09:12:33.001Z'
manufacturer:
$ref: '#/components/schemas/Manufacturer'
Manufacturer:
required:
- name
properties:
name:
type: string
example: ACME Corporation
homePage:
type: string
format: url
example: 'https://www.acme-corp.com'


Image for post
Image for post

Background

How often do we have to deal with integration with third party APIs? I probably spent about 50% - 60% of my time integrating with someone else’s APIs and in some industries you could be spending up to 90% of your time integrating with someone else’s ready-to-go product. In this post I’ll be sharing some of the common issues I’ve faced before I discovered OpenAPI (or commonly known as Swagger) and how OpenAPI helped to resolve them.

Problems

If the word document below looks familiar to you then you can probably sympathize with me. How many hours I spent in the past writing API specifications, how many copies and revisions I kept in the folder, and how I struggled to choose which template to use. …

About

Chewy2Theo

Just another developer who's into lazy tools that can make my life easier, and hopefully yours too.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store