Light OpenAPI parser library in PHP based on the OpenAPI Specification allowing developers to extract easily schema's data.
How to install?
$ composer require nass59/apollo-openapi
What can you do with it?
Get Paths
In OpenAPI terms, paths are endpoints (resources), such as /users or /reports/summary/, that your API exposes.
All paths are relative to the API server URL.
$openAPI = new OpenAPI('config/schemas/', 'apollo.yaml');
$openAPI->getPaths();
/*
* [
* '/articles',
* '/articles/{id}',
* '/images',
* ...
* ]
*/
Get Paths with Operations
In OpenAPI terms, paths are endpoints (resources), such as /users or /reports/summary/, that your API exposes.
Operations are the HTTP methods used to manipulate these paths, such as GET, POST or DELETE.
$openAPI = new OpenAPI('config/schemas/', 'apollo.yaml');
$openAPI->getPathsWithOperations();
/*
* [
* '/articles' => [
* 'get' => [...],
* 'post' => [...],
* ],
* '/articles/{id}' => [
* 'get' => [...],
* ],
* ...
* ]
*/
Get Path with Operations
Get a specific path (i.e endpoint) and return its operations.
$openAPI = new OpenAPI('config/schemas/', 'apollo.yaml');
$openAPI->getPathWithOperations('/articles');
/*
* [
* 'get' => [...],
* 'post' => [...],
* ]
*/
Get the Request Body
The request body usually contains the representation of the resource to be created.
OpenAPI 3.0 provides the requestBody keyword to describe request bodies.
Request bodies are optional by default.
$openAPI = new OpenAPI('config/schemas/', 'apollo.yaml');
$operations = $openAPI->getPathWithOperations('/articles');
$openAPI->getRequestBody($operations['post']);
/*
* [
* '$ref' => '#/components/requestBodies/ArticleBody',
* ]
*/
Get a Definition
OpenAPI 3.0 data types are based on an extended subset JSON Schema Specification Wright Draft 00.
The data types are described using a Schema object.
$openAPI = new OpenAPI('config/schemas/', 'apollo.yaml');
$openAPI->getDefinition('/articles', 'postArticle');
/*
* [
* 'type' => 'object',
* 'required' => ['name', 'headline'],
* 'additionalProperties' => false,
* 'properties' => [
* 'name' => ['type' => 'string'],
* 'headline' => ['type' => 'string'],
* ...
* ]
* ]
*/
Example of Schema
openapi: 3.0.0
servers:
- url: 'https://api.apollo.dev:8091/'
info:
version: "v1-oas3"
title: Apollo API
description: Share images and videos with your friends.
termsOfService: terms
license:
name: MIT
url: https://opensource.org/licenses/MIT
tags:
- name: article
description: Everything about articles
paths:
/articles:
get:
tags:
- article
operationId: getArticles
summary: ''
description: Get a list of articles
parameters:
- name: fields[articles]
in: query
description: List of fields to display separated by a comma.
example: "name,headline"
required: false
schema:
type: string
- name: sort
in: query
description: Field use to sort the result.
example: "-name"
required: false
schema:
type: string
- name: page[offset]
in: query
description: Number of page to skip.
required: false
schema:
type: integer
default: 1
- name: page[limit]
in: query
description: The numbers of items to return.
required: false
schema:
type: integer
default: 20
responses:
'200':
description: Successful operation
content:
application/hal+json:
schema:
$ref: '#/components/schemas/Collection'
post:
tags:
- article
operationId: postArticle
summary: ''
description: Create a new article
responses:
'201':
description: Successful operation
content:
application/hal+json:
schema:
$ref: '#/components/schemas/Article'
'400':
description: Bad request
requestBody:
$ref: '#/components/requestBodies/ArticleBody'
/articles/{id}:
get:
tags:
- article
operationId: getArticle
summary: ''
description: Get a specific article
parameters:
- name: id
in: path
description: The id of the article
required: true
schema:
type: string
responses:
'200':
description: Successful operation
'404':
description: Article not found
put:
tags:
- article
summary: ''
description: Update an existing article
operationId: putArticle
parameters:
- name: id
in: path
description: The id of the article
required: true
schema:
type: string
responses:
'200':
description: Successful operation
content:
application/hal+json:
schema:
$ref: '#/components/schemas/Article'
'400':
description: Bad request
'404':
description: Article not found
requestBody:
$ref: '#/components/requestBodies/ArticleBody'
delete:
tags:
- article
summary: ''
description: Delete a specific article
operationId: deleteArticle
parameters:
- name: id
in: path
description: The id of the article
required: true
schema:
type: string
responses:
'204':
description: Article deleted
'404':
description: Article not found
components:
schemas:
ArticleBody:
type: object
required:
- name
- headline
- article_body
- author
additionalProperties: false
properties:
name:
type: string
example: My first article
headline:
type: string
description: Headline of the article.
example: Traveling is great!
article_body:
type: string
description: The actual body of the article.
example: Traveling is great because...
author:
type: string
description: The author of this content
example: John Doe
article_section:
type: string
example: discovery
enum:
- 'discovery'
- 'travel'
- 'update'
tags:
type: array
items:
type: string
example: 'New York'
Article:
type: object
properties:
article:
$ref: '#/components/schemas/ArticleBody'
Collection:
type: object
properties:
_links:
type: object
_embedded:
type: object
items:
type: object
requestBodies:
ArticleBody:
content:
application/hal+json:
schema:
$ref: '#/components/schemas/ArticleBody'
description: Article object.
required: true
Run tests
$ phpdbg -qrr ./vendor/phpspec/phpspec/bin/phpspec run -f progress