Powering Your API Development with
OpenAPI
Longhorn PHP 2021
Daniel Abernathy
About Me
Home
Dripping Springs, TX
Job
Web Development
- Laravel & Vue.js Developer
- Longhorn PHP Organizer
What's OpenAPI?
"A broadly adopted industry standard for describing modern APIs."
Blueprint
A guide for developers on how to build or consume an API.
Contract
An agreement between all stakeholders on how an API's requests and responses should be structured.
Practical summary:
An OpenAPI document is a machine-readable description of an API's endpoints and the structure of the data in its requests and responses.
2010
- Swagger specification created
2015
- Swagger purchased by SmartBear
- Specification donated to Linux Foundation and rebranded as OpenAPI (v2)
2017
- OpenAPI version 3 released
History
Comparisons
vs. API format specifications like JSON:API
OpenAPI
- Describes your API in whatever format you choose
- Can model an API that conforms to a specification like JSON:API
- Is concerned with the details of your API endpoints and values
JSON:API
- Describes a format that your API must conform to
- Isn't concerned with the particular endpoints or values in your API, only the structure
Benefits of starting with OpenAPI
- Provides a contract that all teams can agree on up-front
- Front-end developers can start building against the description sooner
- Back-end developers can write tests to ensure the implementation meets the description
Benefit of having an OpenAPI file
Documentation
Mock Server
Testing
Validation
(... and more)
OpenAPI Resources
OpenAPI Basics
- Auto-generated from code annotations
- Write JSON or YAML by hand
- (side-by-side with rendered view)
- Using IDE tools
- Postman
- GUI editor (Stoplight)
How to write an OpenAPI file
OpenAPI Basics
{
"openapi": "3.0.0",
"info": {
"title": "Todo MVC",
"version": "",
"description": "A backend API for TodoMVC"
},
"servers": [],
"paths": {},
"components": {}
}
Paths
"/widgets": {
"get": {
"description": "Get all widgets"
"responses": {
"200": {
"description": "OK"
}
}
}
}Paths describe your individual endpoints
They primarily contain "operations", which correspond to HTTP verbs
Paths
"/widgets/{widgetId}": {
"parameters": [
{
"schema": {
"type": "integer"
},
"name": "widgetId",
"in": "path",
"required": true
}
]
}Paths can also contain parameters
Operations
"patch": {
"description": "Update a widget",
"responses": {
"200": {
"description": "OK"
}
},
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
}
}The most important parts of an operation are the request body and the responses.
Schema
Data in OpenAPI is described as JSON Schema.... ish
OpenAPI uses an "extended subset" of an old draft of JSON Schema.
ಠ_ಠ
That is, this used to be the case...
Schema
"schema": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"description": {
"type": "string",
"nullable": true
}
}
}requestBody
"post": {
"requestBody": {
"content": {
"application/json": {
"schema": {
}
}
}
}
}responses
"post": {
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
}
}
}
}
}
}components & $ref
The root level components property lets you store data that you can reuse throughout document
{
"components": {
"schema": {},
"responses": {},
"parameters": {},
"requestBodies": {}
}
}components & $ref
The $ref keyword lets you point to an item in the components section from elsewhere in the document.
{
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Widget"
}
}
}Break
Building an API
git clone https://github.com/dabernathy89/openapi-workshop-2021.git
cd openapi-workshop-2021
git checkout start
composer install
touch database/database.sqlite
cp .env.example .env
env file - delete all `DB_*` settings
env file: `DB_CONNECTION=sqlite`
php artisan key:generate
php artisan migrate:fresh
cd public
php -S localhost:3100Open API Workshop (2021)
By Daniel Abernathy
