Powering Your API Development with

 

OpenAPI

Sunshine PHP 2020

Daniel Abernathy

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

About Me

 

Home

Austin, TX

Job

ReviewPush

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 modeling tools like Postman

OpenAPI

  • Models the structure and schema of requests & responses (but also allows examples!)
  • Tools are built around OpenAPI specification

Postman

  • Models examples of requests
  • Tools are bundled with Postman

Comparisons

vs. API format specifications like JSON:API

OpenAPI

  • Specification for a document (an OpenAPI file)
  • 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

  • Specification for your API itself
  • Describes a format that your API must conform to
  • Isn't concerned with the particular endpoints or values in your API, only the structure

Comparisons

vs. other API description specifications

API Blueprint

RAML

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

OpenAPI Basics

  • Auto-generated from code annotations
     
  • Write JSON or YAML by hand
    • (side-by-side with rendered view)
    • Using IDE tools
       
  • GUI editor (Stoplight)

How to write an OpenAPI file

OpenAPI Basics

{
  "openapi": "3.0.0",
  "info": {
    "title": "Raffle API",
    "version": "",
    "description": "Raffle Application API"
  },
  "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.

ಠ_ಠ

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 a Raffle application with OpenAPI

git clone https://github.com/dabernathy89/openapi-workshop.git
cd openapi-workshop
git checkout start
composer install
npm install && npm run dev
touch database/database.sqlite
cp .env.example .env
php artisan key:generate
php artisan migrate --seed

cd public
php -S localhost:8080

Building a Raffle application with OpenAPI

User

Contest

Contestant

Prize

Begin by writing spec

GET /contests
POST /contests

GET /contests/{contestId}
PATCH /contests/{contestId}
DELETE /contests/{contestId}

GET /contests/{contestId}/prizes
POST /contests/{contestId}/prizes

GET /contests/{contestId}/contestants
POST /contests/{contestId}/contestants

PATCH /contestants/{contestantId}
DELETE /contestants/{contestantId}

PATCH /prizes/{prizeId}
DELETE /prizes/{prizeId}
Made with Slides.com