/data-model-openapi30

DataModels for OpenAPI 3.0.*

Primary LanguagePHPMIT LicenseMIT

Zerotoprod\DataModelOpenapi30

Repo GitHub Actions Workflow Status GitHub Actions Workflow Status Packagist Downloads Packagist Version License wakatime Hits-of-Code

Contents

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.