Powering Your API Development with

 

OpenAPI

Longhorn PHP 2021

Daniel Abernathy

https://slides.com/dabernathy89/open-api-workshop-2021/

About Me

 

Home

Dripping Springs, TX

Job

Mio

Web Development

  • Laravel & Vue.js Developer
  • Longhorn PHP Organizer

What's OpenAPI?

"A broadly adopted industry standard for describing modern APIs."

openapis.org

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

Swagger OpenAPI Guide

OpenAPI.tools

OpenAPI Specification

Official Documentation

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:3100
Made with Slides.com