DataModels for OpenAPI 3.0.* specification.
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.
You can publish this README to your local documentation directory.
This can be useful for providing documentation for AI agents.
This can be done using the included script:
# Publish to default location (./docs/zero-to-prod/data-model-openapi30)
vendor/bin/data-model-openapi30
# Publish to custom directory
vendor/bin/data-model-openapi30 /path/to/your/docs
You can automatically publish documentation by adding the following to your composer.json
:
{
"scripts": {
"post-install-cmd": [
"data-model-openapi30"
],
"post-update-cmd": [
"data-model-openapi30"
]
}
}
use Zerotoprod\DataModelOpenapi30\OpenApi;
$OpenApi = OpenApi::from(json_decode($json, true));
$OpenApi->components->schemas['pet']->description;
You can directly import these files into your project like this:
./vendor/bin/data-model-openapi30 app/DataModelOpenapi30
Test | Status |
---|---|
4.7.2.2 Info Object Example | :white_check_mark: |
4.7.3.2 Contact Object Example | :white_check_mark: |
4.7.4.2 License Object Example | :white_check_mark: |
4.7.5.2 Server Object Example | :white_check_mark: |
4.7.7.2 Components Object Example | :white_check_mark: |
4.7.8.3 Paths Object Example | :white_check_mark: |
4.7.9.2 Path Item Object Example | :white_check_mark: |
4.7.10.2 Operation Object Example | :white_check_mark: |
4.7.11.2 External Documentation Object Example | :white_check_mark: |
4.7.12.5 Parameter Object Examples | :white_check_mark: |
4.7.13.2 Request Body Examples | :white_check_mark: |
4.7.14.2 Media Type Examples | :white_check_mark: |
This section describes the structure of the OpenAPI Description format
This is the root object of the OpenAPI Description.
Field Name | Type | Status |
---|---|---|
openapi | string |
:white_check_mark: |
info | Info Object |
:white_check_mark: |
servers | [Server Object] |
:white_check_mark: |
paths | Paths Object |
:white_check_mark: |
components | Components Object |
:white_check_mark: |
security | Security Requirement Object |
:white_check_mark: |
tags | [Tag Object ] |
:white_check_mark: |
externalDocs | External Documentation Object |
:white_check_mark: |
The object provides metadata about the API.
Field Name | Type | Status |
---|---|---|
title | string |
:white_check_mark: |
description | string |
:white_check_mark: |
termsOfService | string |
:white_check_mark: |
contact | Contact Object |
:white_check_mark: |
license | License Object |
:white_check_mark: |
version | string |
:white_check_mark: |
Contact information for the exposed API.
Field | Type | Status |
---|---|---|
name | string |
:white_check_mark: |
url | string |
:white_check_mark: |
email |
:white_check_mark: |
License information for the exposed API.
Field | Type | Status |
---|---|---|
name | string |
:white_check_mark: |
url | string |
:white_check_mark: |
An object representing a Server.
Field Name | Type | Status |
---|---|---|
url | string |
:white_check_mark: |
description | string |
:white_check_mark: |
variables | Map[string , Server Variable Object ] |
:white_check_mark: |
An object representing a Server Variable for server URL template substitution.
Field Name | Type | Status |
---|---|---|
enum | [string ] |
:white_check_mark: |
default | string |
:white_check_mark: |
description | string |
:white_check_mark: |
Holds a set of reusable objects for different aspects of the OAS.
Field Name | Type | Status |
---|---|---|
schemas | Map[string , Schema Object | Reference Object ] |
:white_check_mark: |
responses | Map[string , Response Object | Reference Object ] |
:white_check_mark: |
parameters | Map[string , Parameter Object | Reference Object ] |
:white_check_mark: |
examples | Map[string , Example Object | Reference Object ] |
:white_check_mark: |
requestBodies | Map[string , Request Body Object | Reference Object ] |
:white_check_mark: |
headers | Map[string , Header Object | Reference Object ] |
:white_check_mark: |
securitySchemes | Map[string , Security Scheme Object | Reference Object ] |
:white_check_mark: |
links | Map[string , Link Object | Reference Object ] |
:white_check_mark: |
callbacks | Map[string , Callback Object | Reference Object ] |
:white_check_mark: |
Holds the relative paths to the individual endpoints and their operations.
Field Name | Type | Status |
---|---|---|
/{path} | Path Item Object | :white_check_mark: |
Describes the operations available on a single path.
Field Name | Type | Status |
---|---|---|
$ref | string |
:white_check_mark: |
summary | string |
:white_check_mark: |
description | string |
:white_check_mark: |
get | Operation Object |
:white_check_mark: |
put | Operation Object |
:white_check_mark: |
post | Operation Object |
:white_check_mark: |
delete | Operation Object |
:white_check_mark: |
options | Operation Object |
:white_check_mark: |
head | Operation Object |
:white_check_mark: |
patch | Operation Object |
:white_check_mark: |
trace | Operation Object |
:white_check_mark: |
servers | Server Object |
:white_check_mark: |
parameters | [Parameter Object | Reference Object ] |
:white_check_mark: |
Describes a single API operation on a path.
Field Name | Type | Status |
---|---|---|
tags | [string ] |
:white_check_mark: |
summary | string |
:white_check_mark: |
description | string |
:white_check_mark: |
externalDocs | External Documentation Object |
:white_check_mark: |
operationId | string |
:white_check_mark: |
parameters | [Parameter Object | Reference Object ] |
:white_check_mark: |
requestBody | Request Body Object | Reference Object |
:white_check_mark: |
responses | Responses Object |
:white_check_mark: |
callbacks | Map[string , Callback Object | Reference Object ] |
:white_check_mark: |
deprecated | boolean |
:white_check_mark: |
security | [Security Requirement Object ] |
:white_check_mark: |
servers | [Server Object ] |
:white_check_mark: |
Allows referencing an external resource for extended documentation.
Field Name | Type | Status |
---|---|---|
description | string |
:white_check_mark: |
url | string |
:white_check_mark: |
Describes a single operation parameter.
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.
These fields MAY be used with either content
or schema
.
Field Name | Type | Status |
---|---|---|
name | string |
:white_check_mark: |
in | string |
:white_check_mark: |
description | string |
:white_check_mark: |
required | boolean |
:white_check_mark: |
deprecated | boolean |
:white_check_mark: |
allowEmptyValue | [boolean ] |
:white_check_mark: |
schema
For simpler scenarios, a schema
and style
can describe the structure and syntax of the parameter.
Field Name | Type | Status |
---|---|---|
style | string |
:white_check_mark: |
explode | boolean |
:white_check_mark: |
allowReserved | boolean |
:white_check_mark: |
schema | Schema Object | Reference Object |
:white_check_mark: |
example | Any | :white_check_mark: |
examples | Map[ string , Example Object | Reference Object ] |
:white_check_mark: |
content
Field Name | Type | Status |
---|---|---|
content | Map[string , Media Type Object ] |
:white_check_mark: |
Describes a single request body.
Field Name | Type | Status |
---|---|---|
description | string |
:white_check_mark: |
content | Map[string , Media Type Object ] |
:white_check_mark: |
required | boolean |
:white_check_mark: |
Each Media Type Object provides schema and examples for the media type identified by its key.
Field Name | Type | Status |
---|---|---|
schema | Schema Object | Reference Object |
:white_check_mark: |
example | Any | :white_check_mark: |
examples | Map[string , Example Object | Reference Object ] |
:white_check_mark: |
encoding | Map[string , Encoding Object ] |
:white_check_mark: |
A single encoding definition applied to a single schema property.
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 |
:white_check_mark: |
headers | Map[string , Header Object | Reference Object ] |
:white_check_mark: |
Field Name | Type | Status |
---|---|---|
style | string |
:white_check_mark: |
explode | boolean |
:white_check_mark: |
allowReserved | boolean |
:white_check_mark: |
A container for the expected responses of an operation. The container maps an HTTP response code to the expected response.
Field Name | Type | Status |
---|---|---|
default | Response Object | Reference Object |
:white_check_mark: |
Field Name | Type | Status |
---|---|---|
HTTP Status Code | Response Object | Reference Object |
:white_check_mark: |
Describes a single response from an API operation, including design-time, static links to operations based on the response.
Field Name | Type | Status |
---|---|---|
description | string |
:white_check_mark: |
headers | Map[string , Header Object | Reference Object] |
:white_check_mark: |
content | Map[string , Media Type Object] |
:white_check_mark: |
links | Map[string , Link Object | Reference Object] |
:white_check_mark: |
An object grouping an internal or external example value with basic summary
and description
metadata.
Field Name | Type | Status |
---|---|---|
summary | string |
:white_check_mark: |
description | string |
:white_check_mark: |
value | Any | :white_check_mark: |
externalValue | string |
:white_check_mark: |
The Link Object represents a possible design-time link for a response.
Field Name | Type | Status |
---|---|---|
operationRef | string |
:white_check_mark: |
operationId | string |
:white_check_mark: |
parameters | Map[string , Any | {expression}] |
:white_check_mark: |
requestBody | Any | {expression} | :white_check_mark: |
description | string |
:white_check_mark: |
server | Server Object |
:white_check_mark: |
Describes a single header for HTTP responses and for individual parts in multipart representations.
These fields MAY be used with either content
or schema
.
Field Name | Type | Status |
---|---|---|
description | string |
:white_check_mark: |
required | boolean |
:white_check_mark: |
deprecated | boolean |
:white_check_mark: |
schema
For simpler scenarios, a schema and style can describe the structure and syntax of the header.
Field Name | Type | Status |
---|---|---|
style | string |
:white_check_mark: |
explode | boolean |
:white_check_mark: |
schema | Schema Object | Reference Object |
:white_check_mark: |
example | Any | :white_check_mark: |
examples | Map[string , Example Object | Reference Object ] |
:white_check_mark: |
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 ] |
:white_check_mark: |
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.
Field | Type | Status |
---|---|---|
name | string |
:white_check_mark: |
description | string |
:white_check_mark: |
description | External Documentation Object |
:white_check_mark: |
A simple object to allow referencing other components in the OpenAPI Description, internally and externally.
Field | Type | Status |
---|---|---|
$ref | string |
:white_check_mark: |
The Schema Object allows the definition of input and output data types.
Field Name | Type | Status |
---|---|---|
title | string |
:white_check_mark: |
multipleOf | number |
:white_check_mark: |
maximum | number |
:white_check_mark: |
exclusiveMaximum | boolean |
:white_check_mark: |
minimum | number |
:white_check_mark: |
exclusiveMinimum | boolean |
:white_check_mark: |
maxLength | integer |
:white_check_mark: |
minLength | integer |
:white_check_mark: |
pattern | string |
:white_check_mark: |
maxItems | integer |
:white_check_mark: |
minItems | integer |
:white_check_mark: |
uniqueItems | boolean |
:white_check_mark: |
maxProperties | integer |
:white_check_mark: |
minProperties | integer |
:white_check_mark: |
required | array |
:white_check_mark: |
enum | array |
:white_check_mark: |
type | string |
:white_check_mark: |
allOf | Reference Object | Schema Object |
:white_check_mark: |
oneOf | Reference Object | Schema Object |
:white_check_mark: |
anyOf | Reference Object | Schema Object |
:white_check_mark: |
not | Reference Object | Schema Object |
:white_check_mark: |
items | Reference Object | Schema Object |
:white_check_mark: |
properties | Reference Object | Schema Object |
:white_check_mark: |
additionalProperties | boolean |Reference Object | Schema Object |
:white_check_mark: |
description | string |
:white_check_mark: |
format | string |
:white_check_mark: |
format | Any |
:white_check_mark: |
Field Name | Type | Status |
---|---|---|
nullable | boolean |
:white_check_mark: |
discriminator | Discriminator Object |
:white_check_mark: |
readOnly | boolean |
:white_check_mark: |
writeOnly | boolean |
:white_check_mark: |
xml | XML Object |
:white_check_mark: |
externalDocs | External Documentation Object |
:white_check_mark: |
example | Any | :white_check_mark: |
deprecated | boolean |
:white_check_mark: |
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.
Field Name | Type | Status |
---|---|---|
propertyName | string |
:white_check_mark: |
mapping | Map[string , string ] |
:white_check_mark: |
A metadata object that allows for more fine-tuned XML model definitions.
Field Name | Type | Status |
---|---|---|
name | string |
:white_check_mark: |
namespace | string |
:white_check_mark: |
prefix | string |
:white_check_mark: |
attribute | boolean |
:white_check_mark: |
wrapped | boolean |
:white_check_mark: |
Defines a security scheme that can be used by the operations.
Field Name | Type | Status |
---|---|---|
type | string |
:white_check_mark: |
description | string |
:white_check_mark: |
name | string |
:white_check_mark: |
in | string |
:white_check_mark: |
scheme | string |
:white_check_mark: |
bearerFormat | string |
:white_check_mark: |
flows | string |
:white_check_mark: |
openIdConnectUrl | string |
:white_check_mark: |
Allows configuration of the supported OAuth Flows.
Field Name | Type | Status |
---|---|---|
implicit | OAuth Flow Object |
:white_check_mark: |
password | OAuth Flow Object |
:white_check_mark: |
clientCredentials | OAuth Flow Object |
:white_check_mark: |
authorizationCode | OAuth Flow Object |
:white_check_mark: |
Defines a security scheme that can be used by the operations.
Field Name | Type | Status |
---|---|---|
authorizationUrl | string |
:white_check_mark: |
tokenUrl | string |
:white_check_mark: |
refreshUrl | string |
:white_check_mark: |
scopes | Map[string , string ] |
:white_check_mark: |
Contributions, issues, and feature requests are welcome! Feel free to check the issues page if you want to contribute.
git checkout -b feature-branch
).git commit -m 'Add some feature'
).git push origin feature-branch
).