Zerotoprod\DataModelOpenapi30

Contents

• Introduction
• Requirements
• Installation
• Usage
• Publishing DataModels
• Local Development
• Contributing

Introduction

DataModels for OpenAPI 3.0.* specification.

Requirements

• PHP 8.1 or higher.

Installation

Install Zerotoprod\DataModelOpenapi30 via Composer:

composer require zero-to-prod/data-model-openapi30

This will add the package to your project’s dependencies and create an autoloader entry for it.

Usage

use Zerotoprod\DataModelOpenapi30\OpenApi;

$OpenApi = OpenApi::from(json_decode($json, true));

$OpenApi->components->schemas['pet']->description;

Publishing DataModels

You can directly import these files into your project like this:

./vendor/bin/data-model-openapi30 app/DataModelOpenapi30

Acceptance Tests

Test	Status
4.7.2.2 Info Object Example	✅
4.7.3.2 Contact Object Example	✅
4.7.4.2 License Object Example	✅
4.7.5.2 Server Object Example	✅
4.7.7.2 Components Object Example	✅
4.7.8.3 Paths Object Example	✅
4.7.9.2 Path Item Object Example	✅
4.7.10.2 Operation Object Example	✅
4.7.11.2 External Documentation Object Example	✅
4.7.12.5 Parameter Object Examples	✅
4.7.13.2 Request Body Examples	✅
4.7.14.2 Media Type Examples	✅

Properties

4.0 Specification

4.7 Schema

This section describes the structure of the OpenAPI Description format

4.7.1 OpenAPI Object

This is the root object of the OpenAPI Description.

4.7.1.1 Fixed Fields

Field Name	Type	Status
openapi	string	✅
info	Info Object	✅
servers	[Server Object]	✅
paths	Paths Object	✅
components	Components Object	✅
security	Security Requirement Object	✅
tags	[Tag Object]	✅
externalDocs	External Documentation Object	✅

4.7.2 Info Object

The object provides metadata about the API.

4.7.2.1 Fixed Fields

Field Name	Type	Status
title	string	✅
description	string	✅
termsOfService	string	✅
contact	Contact Object	✅
license	License Object	✅
version	string	✅

4.7.3 Contact Object

Contact information for the exposed API.

4.7.3.1 Fixed Fields

Field	Type	Status
name	string	✅
url	string	✅
email	email	✅

4.7.4 License Object

License information for the exposed API.

4.7.4.1 Fixed Fields

Field	Type	Status
name	string	✅
url	string	✅

4.7.5 Server Object

An object representing a Server.

4.7.5.1 Fixed Fields

Field Name	Type	Status
url	string	✅
description	string	✅
variables	Map[string, Server Variable Object]	✅

4.7.6 Server Object

An object representing a Server Variable for server URL template substitution.

4.7.6.1 Fixed Fields

Field Name	Type	Status
enum	[string]	✅
default	string	✅
description	string	✅

4.7.7 Components Object

Holds a set of reusable objects for different aspects of the OAS.

4.7.7.1 Fixed Fields

Field Name	Type	Status
schemas	Map[string, Schema Object | Reference Object]	✅
responses	Map[string, Response Object | Reference Object]	✅
parameters	Map[string, Parameter Object | Reference Object]	✅
examples	Map[string, Example Object | Reference Object]	✅
requestBodies	Map[string, Request Body Object | Reference Object]	✅
headers	Map[string, Header Object | Reference Object]	✅
securitySchemes	Map[string, Security Scheme Object | Reference Object]	✅
links	Map[string, Link Object | Reference Object]	✅
callbacks	Map[string, Callback Object | Reference Object]	✅

4.7.8 Paths Object

Holds the relative paths to the individual endpoints and their operations.

4.7.8.1 Patterned Fields

Field Name	Type	Status
/{path}	Path Item Object	✅

4.7.9 Path Item Object

Describes the operations available on a single path.

4.7.9.1 Fixed Fields

Field Name	Type	Status
$ref	string	✅
summary	string	✅
description	string	✅
get	Operation Object	✅
put	Operation Object	✅
post	Operation Object	✅
delete	Operation Object	✅
options	Operation Object	✅
head	Operation Object	✅
patch	Operation Object	✅
trace	Operation Object	✅
servers	Server Object	✅
parameters	[Parameter Object | Reference Object]	✅

4.7.10 Operation Object

Describes a single API operation on a path.

4.7.10.1 Fixed Fields

Field Name	Type	Status
tags	[string]	✅
summary	string	✅
description	string	✅
externalDocs	External Documentation Object	✅
operationId	string	✅
parameters	[Parameter Object | Reference Object]	✅
requestBody	Request Body Object | Reference Object	✅
responses	Responses Object	✅
callbacks	Map[string, Callback Object | Reference Object]	✅
deprecated	boolean	✅
security	[Security Requirement Object]	✅
servers	[Server Object]	✅

4.7.11 External Documentation Object

Allows referencing an external resource for extended documentation.

4.7.11.1 Fixed Fields

Field Name	Type	Status
description	string	✅
url	string	✅

4.7.12 Parameter Object

Describes a single operation parameter.

4.7.12.2 Fixed Fields

The rules for serialization of the parameter are specified in one of two ways. Parameter Objects MUST include either a content field or a schema field, but not both.

4.7.12.2.1 Common Fixed Fields

These fields MAY be used with either content or schema.

Field Name	Type	Status
name	string	✅
in	string	✅
description	string	✅
required	boolean	✅
deprecated	boolean	✅
allowEmptyValue	[boolean]	✅

4.7.12.2.2 Fixed Fields for use with schema

For simpler scenarios, a schema and style can describe the structure and syntax of the parameter.

Field Name	Type	Status
style	string	✅
explode	boolean	✅
allowReserved	boolean	✅
schema	Schema Object | Reference Object	✅
example	Any	✅
examples	Map[ string, Example Object | Reference Object]	✅

4.7.12.2.3 Fixed Fields for use with content

Field Name	Type	Status
content	Map[string, Media Type Object]	✅

4.7.13 Request Body Object

Describes a single request body.

4.7.13.1 Fixed Fields

Field Name	Type	Status
description	string	✅
content	Map[string, Media Type Object]	✅
required	boolean	✅

4.7.14 Media Type Object

Each Media Type Object provides schema and examples for the media type identified by its key.

4.7.14.1 Fixed Fields

Field Name	Type	Status
schema	Schema Object | Reference Object	✅
example	Any	✅
examples	Map[string, Example Object | Reference Object]	✅
encoding	Map[string, Encoding Object]	✅

4.7.15 Encoding Object

A single encoding definition applied to a single schema property.

4.7.15.1 Fixed Fields

4.7.15.1.1 Common Fixed Fields

These fields MAY be used either with or without the RFC6570-style serialization fields defined in the next section below.

Field Name	Type	Status
contentType	string	✅
headers	Map[string, Header Object | Reference Object]	✅

4.7.15.1.2 Fixed Fields for RFC6570-style Serialization

Field Name	Type	Status
style	string	✅
explode	boolean	✅
allowReserved	boolean	✅

4.7.16 Responses Object

A container for the expected responses of an operation. The container maps an HTTP response code to the expected response.

4.7.16.1 Fixed Fields

Field Name	Type	Status
default	Response Object | Reference Object	✅

4.7.16.2 Patterned Fields

Field Name	Type	Status
HTTP Status Code	Response Object | Reference Object	✅

4.7.17 Response Object

Describes a single response from an API operation, including design-time, static links to operations based on the response.

4.7.17.1 Fixed Fields

Field Name	Type	Status
description	string	✅
headers	Map[string, Header Object | Reference Object]	✅
content	Map[string, Media Type Object]	✅
links	Map[string, Link Object | Reference Object]	✅

4.7.19 Example Object

An object grouping an internal or external example value with basic summary and description metadata.

4.7.19.1 Fixed Fields

Field Name	Type	Status
summary	string	✅
description	string	✅
value	Any	✅
externalValue	string	✅

4.7.20 Link Object

The Link Object represents a possible design-time link for a response.

4.7.20.1 Fixed Fields

Field Name	Type	Status
operationRef	string	✅
operationId	string	✅
parameters	Map[string, Any | {expression}]	✅
requestBody	Any | {expression}	✅
description	string	✅
server	Server Object	✅

4.7.21 Header Object

Describes a single header for HTTP responses and for individual parts in multipart representations.

4.7.21.1 Fixed Fields

4.7.21.1.1 Common Fixed Fields

These fields MAY be used with either content or schema.

Field Name	Type	Status
description	string	✅
required	boolean	✅
deprecated	boolean	✅

4.7.21.1.2 Fixed Fields for use with schema

For simpler scenarios, a schema and style can describe the structure and syntax of the header.

Field Name	Type	Status
style	string	✅
explode	boolean	✅
schema	Schema Object | Reference Object	✅
example	Any	✅
examples	Map[string, Example Object | Reference Object]	✅

4.7.21.1.3 Fixed Fields for use with content

For more complex scenarios, the content field can define the media type and schema of the header, as well as give examples of its use.

Field Name	Type	Status
content	Map[string, Media Type Object]	✅

4.7.22 Tag Object

Adds metadata to a single tag that is used by the Operation Object. It is not mandatory to have a Tag Object per tag defined in the Operation Object instances.

4.7.22.1 Fixed Fields

Field	Type	Status
name	string	✅
description	string	✅
description	External Documentation Object	✅

4.7.23 Reference Object

A simple object to allow referencing other components in the OpenAPI Description, internally and externally.

4.7.23.1 Fixed Fields

Field	Type	Status
$ref	string	✅

4.7.24 Schema Object

The Schema Object allows the definition of input and output data types.

4.7.24.1 JSON Schema Keywords

Field Name	Type	Status
title	string	✅
multipleOf	number	✅
maximum	number	✅
exclusiveMaximum	boolean	✅
minimum	number	✅
exclusiveMinimum	boolean	✅
maxLength	integer	✅
minLength	integer	✅
pattern	string	✅
maxItems	integer	✅
minItems	integer	✅
uniqueItems	boolean	✅
maxProperties	integer	✅
minProperties	integer	✅
required	array	✅
enum	array	✅
type	string	✅
allOf	Reference Object | Schema Object	✅
oneOf	Reference Object | Schema Object	✅
anyOf	Reference Object | Schema Object	✅
not	Reference Object | Schema Object	✅
items	Reference Object | Schema Object	✅
properties	Reference Object | Schema Object	✅
additionalProperties	boolean |Reference Object | Schema Object	✅
description	string	✅
format	string	✅
format	Any	✅

4.7.24.2 Fixed Fields

Field Name	Type	Status
nullable	boolean	✅
discriminator	Discriminator Object	✅
readOnly	boolean	✅
writeOnly	boolean	✅
xml	XML Object	✅
externalDocs	External Documentation Object	✅
example	Any	✅
deprecated	boolean	✅

4.7.25 Discriminator Object

When request bodies or response payloads may be one of a number of different schemas, a Discriminator Object gives a hint about the expected schema of the document.

4.7.25.1 Fixed Fields

Field Name	Type	Status
propertyName	string	✅
mapping	Map[string, string]	✅

4.7.26 XML Object

A metadata object that allows for more fine-tuned XML model definitions.

4.7.26.1 Fixed Fields

Field Name	Type	Status
name	string	✅
namespace	string	✅
prefix	string	✅
attribute	boolean	✅
wrapped	boolean	✅

4.7.27 Security Scheme Object

Defines a security scheme that can be used by the operations.

4.7.27.1 Fixed Fields

Field Name	Type	Status
type	string	✅
description	string	✅
name	string	✅
in	string	✅
scheme	string	✅
bearerFormat	string	✅
flows	string	✅
openIdConnectUrl	string	✅

4.7.28 OAuth Flows Object

Allows configuration of the supported OAuth Flows.

4.7.28.1 Fixed Fields

Field Name	Type	Status
implicit	OAuth Flow Object	✅
password	OAuth Flow Object	✅
clientCredentials	OAuth Flow Object	✅
authorizationCode	OAuth Flow Object	✅

4.7.29 OAuth Flow Object

Defines a security scheme that can be used by the operations.

4.7.29.1 Fixed Fields

Field Name	Type	Status
authorizationUrl	string	✅
tokenUrl	string	✅
refreshUrl	string	✅
scopes	Map[string, string]	✅

Contributing

Contributions, issues, and feature requests are welcome! Feel free to check the issues page if you want to contribute.

1. Fork the repository.
2. Create a new branch (git checkout -b feature-branch).
3. Commit changes (git commit -m 'Add some feature').
4. Push to the branch (git push origin feature-branch).
5. Create a new Pull Request.