示例
本页面是根据 swagger-php 源文件自动生成的。
本页面是根据 swagger-php 源文件自动生成的。
如有改进意见，请前往 GitHub 并创建 PR 😉
API
一个使用 枚举（enums）、**特性（traits）和回调（callbacks）**的简单 API 示例。
NameTrait.php
<?php
declare(strict_types=1);
/**
* @license Apache 2.0
*/
namespace OpenApi\Examples\Specs\Api\Attributes;
use OpenApi\Attributes as OAT;
/**
* A Name.
*/
#[OAT\Schema()]
trait NameTrait
{
#[OAT\Property(description: 'The name.')]
public $name;
}
<?php
declare(strict_types=1);
/**
* @license Apache 2.0
*/
namespace OpenApi\Examples\Specs\Api\Annotations;
use OpenApi\Annotations as OA;
/**
* A Name.
*
* @OA\Schema
*/
trait NameTrait
{
/**
* The name.
*
* @OA\Property
*/
public $name;
}
OpenApiSpec.php
<?php declare(strict_types=1);
/**
* @license Apache 2.0
*/
namespace OpenApi\Examples\Specs\Api\Attributes;
use OpenApi\Attributes as OAT;
/**
* The Spec.
*/
#[OAT\OpenApi(openapi: OAT\OpenApi::VERSION_3_1_0, security: [['bearerAuth' => []]])]
#[OAT\Info(
version: '1.0.0',
title: 'Basic single file API',
attachables: [new OAT\Attachable()]
)]
#[OAT\License(name: 'MIT', identifier: 'MIT')]
#[OAT\Server(url: 'https://localhost/api', description: 'API server')]
#[OAT\SecurityScheme(securityScheme: 'bearerAuth', type: 'http', scheme: 'bearer', description: 'Basic Auth')]
#[OAT\Tag(name: 'products', description: 'All about products')]
#[OAT\Tag(name: 'catalog', description: 'Catalog API')]
class OpenApiSpec
{
}
<?php declare(strict_types=1);
/**
* @license Apache 2.0
*/
namespace OpenApi\Examples\Specs\Api\Annotations;
use OpenApi\Annotations as OA;
/**
* The Spec.
*
* @OA\OpenApi(
* openapi="3.1.0",
* security={{"bearerAuth": {}}}
* )
* @OA\Info(
* version="1.0.0",
* title="Basic single file API",
* @OA\License(name="MIT", identifier="MIT", @OA\Attachable)
* )
* @OA\Server(
* url="https://localhost/api",
* description="API server"
* )
* @OA\SecurityScheme(
* securityScheme="bearerAuth",
* type="http",
* scheme="bearer",
* description="Basic Auth"
* )
* @OA\Tag(
* name="products",
* description="All about products"
* )
* @OA\Tag(
* name="catalog",
* description="Catalog API"
* )
*/
class OpenApiSpec
{
}
Product.php
<?php declare(strict_types=1);
/**
* @license Apache 2.0
*/
namespace OpenApi\Examples\Specs\Api\Attributes;
use OpenApi\Attributes as OAT;
use OpenApi\Examples\Specs\Api\ProductInterface;
/**
* A Product description ignored.
*/
#[OAT\Schema(title: 'Product', description: 'A Product.')]
class Product implements ProductInterface
{
use NameTrait;
/**
* The kind.
*/
#[OAT\Property(property: 'kind')]
public const KIND = 'Virtual';
#[OAT\Property(description: 'The id.', format: 'int64', example: 1)]
/**
* The id.
*/
public $id;
public function __construct(
#[OAT\Property()]
public int $quantity,
#[OAT\Property(default: null, example: null)]
public ?string $brand,
#[OAT\Property()]
public Colour $colour,
#[OAT\Property(type: 'string')]
public \DateTimeInterface $releasedAt,
) {
}
}
<?php declare(strict_types=1);
/**
* @license Apache 2.0
*/
namespace OpenApi\Examples\Specs\Api\Annotations;
use OpenApi\Annotations as OA;
use OpenApi\Examples\Specs\Api\ProductInterface;
/**
* A Product.
*
* @OA\Schema(
* title="Product"
* )
*/
class Product implements ProductInterface
{
use NameTrait;
/** @OA\Property */
public int $quantity;
/** @OA\Property(nullable=true, default=null, example=null) */
public string $brand;
/** @OA\Property */
public Colour $colour;
/**
* The id.
*
* @OA\Property(format="int64", example=1)
*/
public $id;
/**
* The kind.
*
* @OA\Property(property="kind")
*/
public const KIND = 'Virtual';
public function __construct(
/**
* @OA\Property(type="string")
*/
public \DateTimeInterface $releasedAt,
) {
}
}
Colour.php
<?php declare(strict_types=1);
/**
* @license Apache 2.0
*/
namespace OpenApi\Examples\Specs\Api\Attributes;
use OpenApi\Attributes as OAT;
/**
* A Colour.
*/
#[OAT\Schema()]
enum Colour
{
case GREEN;
case BLUE;
case RED;
}
<?php declare(strict_types=1);
/**
* @license Apache 2.0
*/
namespace OpenApi\Examples\Specs\Api\Annotations;
use OpenApi\Annotations as OA;
/**
* A Colour.
*
* @OA\Schema()
*/
enum Colour
{
case GREEN;
case BLUE;
case RED;
}
Server.php
<?php declare(strict_types=1);
/**
* @license Apache 2.0
*/
namespace OpenApi\Examples\Specs\Api\Attributes;
use OpenApi\Attributes as OAT;
#[OAT\Server(
url: 'https://example.localhost',
description: 'The local environment.'
)]
#[OAT\Server(
url: 'https://example.com',
description: 'The production server.'
)]
/**
* A Server.
*/
class Server
{
}
<?php declare(strict_types=1);
/**
* @license Apache 2.0
*/
namespace OpenApi\Examples\Specs\Api\Annotations;
use OpenApi\Annotations as OA;
/**
* A Server.
*
* @OA\Server(
* url="https://example.localhost",
* description="The local environment."
* )
* @OA\Server(
* url="https://example.com",
* description="The production server."
* )
*/
class Server
{
}
ProductController.php
<?php declare(strict_types=1);
/**
* @license Apache 2.0
*/
namespace OpenApi\Examples\Specs\Api\Attributes;
use OpenApi\Attributes as OAT;
use OpenApi\Tests\Fixtures\Attributes as OAF;
/**
* The Controller.
*/
class ProductController
{
/**
* Get a product.
*
* @param ?int $product_id the product id
*/
#[OAT\Get(path: '/products/{product_id}', tags: ['products'], operationId: 'getProducts')]
#[OAT\Response(
response: 200,
description: 'successful operation',
content: [new OAT\MediaType(mediaType: 'application/json', schema: new OAT\Schema(ref: Product::class))],
headers: [
new OAT\Header(header: 'X-Rate-Limit', description: 'calls per hour allowed by the user', schema: new OAT\Schema(type: 'integer', format: 'int32')),
]
)]
#[OAT\Response(response: 401, description: 'oops')]
#[OAF\CustomAttachable(value: 'operation')]
public function getProduct(
#[OAT\PathParameter]
?int $product_id
) {
}
#[OAT\Post(path: '/products', tags: ['products'], operationId: 'addProducts', summary: 'Add products')]
#[OAT\Response(
response: 200,
description: 'successful operation',
content: new OAT\JsonContent(ref: Product::class)
)]
#[OAT\RequestBody(
required: true,
description: 'New product',
content: [new OAT\MediaType(
mediaType: 'application/json',
schema: new OAT\Schema(
type: 'array',
items: new OAT\Items(type: Product::class)
)
)]
)]
/**
* Add a product.
*/
public function addProduct()
{
}
#[OAT\Get(path: '/products', tags: ['products', 'catalog'], operationId: 'getAll')]
#[OAT\Response(
response: 200,
description: 'successful operation',
content: new OAT\JsonContent(
type: 'object',
required: ['data'],
properties: [
new OAT\Property(
property: 'data',
type: 'array',
items: new OAT\Items(ref: Product::class)
),
]
)
)]
/**
* Get all.
*/
#[OAT\Response(response: 401, description: 'oops')]
public function getAll()
{
}
#[OAT\Post(
path: '/subscribe',
operationId: 'subscribe',
summary: 'Subscribe to product webhook',
tags: ['products'],
callbacks: [
'onChange' => [
'{$request.query.callbackUrl}' => [
'post' => [
'requestBody' => new OAT\RequestBody(
description: 'subscription payload',
content: [
new OAT\MediaType(
mediaType: 'application/json',
schema: new OAT\Schema(
properties: [
new OAT\Property(
property: 'timestamp',
description: 'time of change',
type: 'string',
format: 'date-time'
),
]
)
),
]
),
],
'responses' => [
'200' => [
'description' => 'Your server implementation should return this HTTP status code if the data was received successfully',
],
],
],
],
]
)]
#[OAT\Parameter(
name: 'callbackUrl',
in: 'query'
)]
#[OAT\Response(
response: 200,
description: 'callbackUrl registered'
)]
public function subscribe()
{
}
}
<?php declare(strict_types=1);
/**
* @license Apache 2.0
*/
namespace OpenApi\Examples\Specs\Api\Annotations;
use OpenApi\Annotations as OA;
/**
* The Controller.
*/
class ProductController
{
/**
* Get a product.
*
* @OA\Get(
* tags={"products"},
* path="/products/{product_id}",
* operationId="getProducts",
* @OA\PathParameter(
* name="product_id",
* required=false,
* @OA\Schema(type="integer")
* ),
* @OA\Response(
* response=200,
* description="successful operation",
* @OA\Header(
* header="X-Rate-Limit",
* description="calls per hour allowed by the user",
* @OA\Schema(
* type="integer",
* format="int32"
* )
* ),
* @OA\MediaType(mediaType="application/json", @OA\Schema(ref="#/components/schemas/Product"))
* ),
* @OA\Response(
* response=401,
* description="oops"
* )
* )
*
* @param ?int $product_id the product id
*/
public function getProduct(?int $product_id)
{
}
/**
* Add a product.
*
* @OA\Post(
* path="/products",
* tags={"products"},
* summary="Add products",
* operationId="addProducts",
* @OA\Response(
* response=200,
* description="successful operation",
* @OA\JsonContent(ref="#/components/schemas/Product")
* ),
* @OA\RequestBody(
* description="New product",
* required=true,
* @OA\MediaType(
* mediaType="application/json",
* @OA\Schema(
* type="array",
* @OA\Items(ref="#/components/schemas/Product")
* )
* )
* )
* )
*/
public function addProduct()
{
}
/**
* Get all.
*
* @OA\Get(
* tags={"products", "catalog"},
* path="/products",
* operationId="getAll",
* @OA\Response(
* response=200,
* description="successful operation",
* @OA\JsonContent(
* type="object",
* required={"data"},
* @OA\Property(
* property="data",
* type="array",
* @OA\Items(ref="#/components/schemas/Product")
* )
* )
* ),
* @OA\Response(
* response=401,
* description="oops"
* )
* )
*/
public function getAll()
{
}
/**
* @OA\Post(
* path="/subscribe",
* tags={"products"},
* operationId="subscribe",
* summary="Subscribe to product webhook",
* @OA\Parameter(
* name="callbackUrl",
* in="query"
* ),
* @OA\Response(
* response=200,
* description="callbackUrl registered"
* ),
* callbacks={
* "onChange": {
* "{$request.query.callbackUrl}": {
* "post": {
* "requestBody": @OA\RequestBody(
* description="subscription payload",
* @OA\MediaType(
* mediaType="application/json",
* @OA\Schema(
* @OA\Property(
* property="timestamp",
* description="time of change",
* type="string",
* format="date-time"
* )
* )
* )
* )
* },
* "responses": {
* "200": {
* "description": "Your server implementation should return this HTTP status code if the data was received successfully"
* }
* }
* }
* }
* }
* )
*/
public function subscribe()
{
}
}
Petstore
经典的宠物商店示例应用。使用 OAuth。
Security.php
<?php
/**
* @license Apache 2.0
*/
namespace OpenApi\Examples\Specs\Petstore\Attributes;
use OpenApi\Attributes as OAT;
#[OAT\SecurityScheme(
type: 'oauth2',
name: 'petstore_auth',
securityScheme: 'petstore_auth',
flows: [
new OAT\Flow(
flow: 'implicit',
authorizationUrl: 'http://petstore.swagger.io/oauth/dialog',
scopes: [
'write:pets' => 'modify pets in your account',
'read:pets' => 'read your pets',
]
),
]
)]
#[OAT\SecurityScheme(
type: 'apiKey',
name: 'api_key',
in: 'header',
securityScheme: 'api_key',
)]
class Security
{
}
<?php
/**
* @license Apache 2.0
*/
namespace OpenApi\Examples\Specs\Petstore\Annotations;
use OpenApi\Annotations as OA;
/**
* @OA\SecurityScheme(
* type="oauth2",
* name="petstore_auth",
* securityScheme="petstore_auth",
* @OA\Flow(
* flow="implicit",
* authorizationUrl="http://petstore.swagger.io/oauth/dialog",
* scopes={
* "write:pets": "modify pets in your account",
* "read:pets": "read your pets",
* }
* )
* )
* @OA\SecurityScheme(
* type="apiKey",
* in="header",
* securityScheme="api_key",
* name="api_key"
* )
*/
class Security
{
}
Controllers/UserController.php
<?php
/**
* @license Apache 2.0
*/
namespace OpenApi\Examples\Specs\Petstore\Attributes\Controllers;
use OpenApi\Attributes as OAT;
use OpenApi\Examples\Specs\Petstore\Attributes\Models\User;
use OpenApi\Examples\Specs\Petstore\Attributes\Models\UserArrayRequestBody;
/**
* Class User.
*
* @author Donii Sergii <doniysa@gmail.com>
*/
class UserController
{
#[OAT\Post(
path: '/user',
tags: ['user'],
summary: 'Create user',
description: 'This can only be done by the logged in user.',
operationId: 'createUser',
responses: [
new OAT\Response(
response: 'default',
description: 'successful operation'
),
],
requestBody: new OAT\RequestBody(
description: 'Create user object',
required: true,
content: new OAT\JsonContent(
ref: User::class
)
)
)]
public function createUser()
{
}
#[OAT\Post(
path: '/user/createWithArray',
tags: ['user'],
summary: 'Create list of users with given input array',
operationId: 'createUsersWithListInput',
responses: [
new OAT\Response(
response: 'default',
description: 'successful operation'
),
],
requestBody: new OAT\RequestBody(
ref: UserArrayRequestBody::class
)
)]
public function createUsersWithListInput()
{
}
#[OAT\Get(
path: '/user/login',
tags: ['user'],
summary: 'Logs user into system',
operationId: 'loginUser',
parameters: [
new OAT\Parameter(
name: 'username',
in: 'query',
description: 'The user name for login',
required: true,
schema: new OAT\Schema(
type: 'string'
)
),
new OAT\Parameter(
name: 'password',
in: 'query',
required: true,
schema: new OAT\Schema(
type: 'string'
)
),
],
responses: [
new OAT\Response(
response: 200,
description: 'successful operation',
headers: [
new OAT\Header(
header: 'X-Rate-Limit',
description: 'calls per hour allowed by the user',
schema: new OAT\Schema(
type: 'integer',
format: 'int32'
)
),
new OAT\Header(
header: 'X-Expires-After',
description: 'date in UTC when token expires',
schema: new OAT\Schema(
type: 'string',
format: 'datetime'
)
),
],
content: [
new OAT\JsonContent(
type: 'string'
),
new OAT\XmlContent(
type: 'string'
),
]
),
new OAT\Response(
response: 400,
description: 'Invalid username/password supplied'
),
]
)]
public function loginUser()
{
}
#[OAT\Get(
path: '/user/logout',
tags: ['user'],
summary: 'Logs out current logged in user session',
operationId: 'logoutUser',
responses: [
new OAT\Response(
response: 'default',
description: 'successful operation'
),
]
)]
public function logoutUser()
{
}
#[OAT\Get(
path: '/user/{username}',
summary: 'Get user by user name',
operationId: 'getUserByName',
parameters: [
new OAT\PathParameter(
name: 'username',
required: true,
schema: new OAT\Schema(
type: 'string'
)
),
],
responses: [
new OAT\Response(
response: 200,
description: 'successful operation',
content: [
new OAT\JsonContent(
ref: User::class
),
new OAT\XmlContent(
ref: User::class
),
]
),
new OAT\Response(
response: 400,
description: 'Invalid username supplied'
),
new OAT\Response(
response: 404,
description: 'User not found'
),
]
)]
public function getUserByName()
{
}
#[OAT\Put(
path: '/user/{username}',
summary: 'Update user',
description: 'This can only be done by the logged in user.',
operationId: 'updateUser',
parameters: [
new OAT\PathParameter(
name: 'username',
required: true,
description: 'name that to be updated',
schema: new OAT\Schema(
type: 'string'
)
),
],
responses: [
new OAT\Response(
response: 400,
description: 'Invalid user supplied'
),
new OAT\Response(
response: 404,
description: 'User not found'
),
],
requestBody: new OAT\RequestBody(
description: 'Updated user object',
required: true,
content: new OAT\JsonContent(
ref: User::class
)
)
)]
public function updateUser()
{
}
#[OAT\Delete(
path: '/user/{username}',
summary: 'Delete user',
description: 'This can only be done by the logged in user.',
operationId: 'deleteUser',
parameters: [
new OAT\Parameter(
name: 'username',
in: 'path',
description: 'The name that needs to be deleted',
required: true,
schema: new OAT\Schema(
type: 'string'
)
),
],
responses: [
new OAT\Response(
response: 400,
description: 'Invalid username supplied'
),
new OAT\Response(
response: 404,
description: 'User not found'
),
]
)]
public function deleteUser()
{
}
}
<?php
/**
* @license Apache 2.0
*/
namespace OpenApi\Examples\Specs\Petstore\Annotations\Controllers;
use OpenApi\Annotations as OA;
/**
* Class User.
*
* @author Donii Sergii <doniysa@gmail.com>
*/
class UserController
{
/**
* @OA\Post(
* path="/user",
* tags={"user"},
* summary="Create user",
* description="This can only be done by the logged in user.",
* operationId="createUser",
* @OA\Response(
* response="default",
* description="successful operation"
* ),
* @OA\RequestBody(
* description="Create user object",
* required=true,
* @OA\JsonContent(ref="#/components/schemas/User")
* )
* )
*/
public function createUser()
{
}
/**
* @OA\Post(
* path="/user/createWithArray",
* tags={"user"},
* summary="Create list of users with given input array",
* operationId="createUsersWithListInput",
* @OA\Response(
* response="default",
* description="successful operation"
* ),
* @OA\RequestBody(ref="#/components/requestBodies/UserArray")
* )
*/
public function createUsersWithListInput()
{
}
/**
* @OA\Get(
* path="/user/login",
* tags={"user"},
* summary="Logs user into system",
* operationId="loginUser",
* @OA\Parameter(
* name="username",
* in="query",
* description="The user name for login",
* required=true,
* @OA\Schema(
* type="string"
* )
* ),
* @OA\Parameter(
* name="password",
* in="query",
* required=true,
* @OA\Schema(
* type="string",
* )
* ),
* @OA\Response(
* response=200,
* description="successful operation",
* @OA\Header(
* header="X-Rate-Limit",
* description="calls per hour allowed by the user",
* @OA\Schema(
* type="integer",
* format="int32"
* )
* ),
* @OA\Header(
* header="X-Expires-After",
* description="date in UTC when token expires",
* @OA\Schema(
* type="string",
* format="datetime"
* )
* ),
* @OA\JsonContent(
* type="string"
* ),
* @OA\MediaType(
* mediaType="application/xml",
* @OA\Schema(
* type="string"
* )
* )
* ),
* @OA\Response(
* response=400,
* description="Invalid username/password supplied"
* )
* )
*/
public function loginUser()
{
}
/**
* @OA\Get(
* path="/user/logout",
* tags={"user"},
* summary="Logs out current logged in user session",
* operationId="logoutUser",
* @OA\Response(
* response="default",
* description="successful operation"
* )
* )
*/
public function logoutUser()
{
}
/**
* @OA\Get(
* path="/user/{username}",
* summary="Get user by user name",
* operationId="getUserByName",
* @OA\Parameter(
* name="username",
* in="path",
* required=true,
* @OA\Schema(
* type="string"
* )
* ),
* @OA\Response(
* response=200,
* description="successful operation",
* @OA\JsonContent(ref="#/components/schemas/User"),
* @OA\MediaType(
* mediaType="application/xml",
* @OA\Schema(ref="#/components/schemas/User")
* )
* ),
* @OA\Response(
* response=400,
* description="Invalid username supplied"
* ),
* @OA\Response(
* response=404,
* description="User not found"
* ),
* )
*/
public function getUserByName()
{
}
/**
* @OA\Put(
* path="/user/{username}",
* summary="Update user",
* description="This can only be done by the logged in user.",
* operationId="updateUser",
* @OA\Parameter(
* name="username",
* in="path",
* description="name that to be updated",
* required=true,
* @OA\Schema(
* type="string"
* )
* ),
* @OA\Response(
* response=400,
* description="Invalid user supplied"
* ),
* @OA\Response(
* response=404,
* description="User not found"
* ),
* @OA\RequestBody(
* description="Updated user object",
* required=true,
* @OA\JsonContent(ref="#/components/schemas/User")
* )
* )
*/
public function updateUser()
{
}
/**
* @OA\Delete(
* path="/user/{username}",
* summary="Delete user",
* description="This can only be done by the logged in user.",
* operationId="deleteUser",
* @OA\Parameter(
* name="username",
* in="path",
* description="The name that needs to be deleted",
* required=true,
* @OA\Schema(
* type="string"
* )
* ),
* @OA\Response(
* response=400,
* description="Invalid username supplied",
* ),
* @OA\Response(
* response=404,
* description="User not found",
* )
* )
*/
public function deleteUser()
{
}
}
Controllers/StoreController.php
<?php
/**
* @license Apache 2.0
*/
namespace OpenApi\Examples\Specs\Petstore\Attributes\Controllers;
use OpenApi\Attributes as OAT;
use OpenApi\Examples\Specs\Petstore\Attributes\Models\Order;
/**
* Class Store.
*
* @author Donii Sergii <doniysa@gmail.com>
*/
class StoreController
{
#[OAT\Get(
path: '/store',
tags: ['store'],
summary: 'Returns pet inventories by status',
description: 'Returns a map of status codes to quantities',
operationId: 'getInventory',
responses: [
new OAT\Response(
response: 200,
description: 'successful operation',
content: new OAT\JsonContent(
additionalProperties: new OAT\AdditionalProperties(
type: 'integer',
format: 'int32'
)
)
),
],
security: [
[
'api_key' => [
],
],
]
)]
public function getInventory()
{
}
#[OAT\Post(
path: '/store/order',
tags: ['store'],
summary: 'Place an order for a pet',
operationId: 'placeOrder',
responses: [
new OAT\Response(
response: 200,
description: 'successful operation',
content: [
new OAT\JsonContent(
ref: Order::class
),
new OAT\XmlContent(
ref: Order::class
),
],
),
],
requestBody: new OAT\RequestBody(
description: 'order placed for purchasing the pet',
required: true,
content: new OAT\JsonContent(
ref: Order::class
)
)
)]
public function placeOrder()
{
}
#[OAT\Get(
path: '/store/order/{orderId}',
tags: ['store'],
description: 'For valid response try integer IDs with value >= 1 and <= 10. Other values will generated exceptions',
operationId: 'getOrderById',
parameters: [
new OAT\Parameter(
name: 'orderId',
in: 'path',
description: 'ID of pet that needs to be fetched',
required: true,
schema: new OAT\Schema(
type: 'integer',
format: 'int64',
minimum: 1,
maximum: 10
)
),
],
responses: [
new OAT\Response(
response: 200,
description: 'successful operation',
content: [
new OAT\JsonContent(
ref: Order::class
),
new OAT\XmlContent(
ref: Order::class
),
],
),
new OAT\Response(
response: 400,
description: 'Invalid ID supplied'
),
new OAT\Response(
response: 404,
description: 'Order not found'
),
],
)]
public function getOrderById()
{
}
#[OAT\Delete(
path: '/store/order/{orderId}',
tags: ['store'],
summary: 'Delete purchase order by ID',
description: 'For valid response try integer IDs with positive integer value. Negative or non-integer values will generate API errors',
operationId: 'deleteOrder',
parameters: [
new OAT\Parameter(
name: 'orderId',
in: 'path',
description: 'ID of the order that needs to be deleted',
required: true,
schema: new OAT\Schema(
type: 'integer',
format: 'int64',
minimum: 1
)
),
],
responses: [
new OAT\Response(
response: 400,
description: 'Invalid ID supplied'
),
new OAT\Response(
response: 404,
description: 'Order not found'
),
],
)]
public function deleteOrder()
{
}
}
<?php
/**
* @license Apache 2.0
*/
namespace OpenApi\Examples\Specs\Petstore\Annotations\Controllers;
use OpenApi\Annotations as OA;
/**
* Class Store.
*
* @author Donii Sergii <doniysa@gmail.com>
*/
class StoreController
{
/**
* @OA\Get(
* path="/store",
* tags={"store"},
* summary="Returns pet inventories by status",
* description="Returns a map of status codes to quantities",
* operationId="getInventory",
* @OA\Response(
* response=200,
* description="successful operation",
* @OA\JsonContent(
* @OA\AdditionalProperties(
* type="integer",
* format="int32"
* )
* )
* ),
* security={
* {"api_key": {}}
* }
* )
*/
public function getInventory()
{
}
/**
* @OA\Post(
* path="/store/order",
* tags={"store"},
* summary="Place an order for a pet",
* operationId="placeOrder",
* @OA\Response(
* response=200,
* description="successful operation",
* @OA\JsonContent(ref="#/components/schemas/Order"),
* @OA\XmlContent(ref="#/components/schemas/Order")
* ),
* @OA\RequestBody(
* description="order placed for purchasing the pet",
* required=true,
* @OA\JsonContent(ref="#/components/schemas/Order")
* )
* )
*/
public function placeOrder()
{
}
/**
* @OA\Get(
* path="/store/order/{orderId}",
* tags={"store"},
* description="For valid response try integer IDs with value >= 1 and <= 10. Other values will generated exceptions",
* operationId="getOrderById",
* @OA\Parameter(
* name="orderId",
* in="path",
* description="ID of pet that needs to be fetched",
* required=true,
* @OA\Schema(
* type="integer",
* format="int64",
* maximum=10,
* minimum=1
* )
* ),
* @OA\Response(
* response=200,
* description="successful operation",
* @OA\JsonContent(ref="#/components/schemas/Order"),
* @OA\MediaType(
* mediaType="application/xml",
* @OA\Schema(ref="#/components/schemas/Order")
* )
* ),
* @OA\Response(
* response=400,
* description="Invalid ID supplied"
* ),
* @OA\Response(
* response=404,
* description="Order not found"
* )
* )
*/
public function getOrderById()
{
}
/**
* @OA\Delete(
* path="/store/order/{orderId}",
* tags={"store"},
* summary="Delete purchase order by ID",
* description="For valid response try integer IDs with positive integer value. Negative or non-integer values will generate API errors",
* operationId="deleteOrder",
* @OA\Parameter(
* name="orderId",
* in="path",
* required=true,
* description="ID of the order that needs to be deleted",
* @OA\Schema(
* type="integer",
* format="int64",
* minimum=1
* )
* ),
* @OA\Response(
* response=400,
* description="Invalid ID supplied"
* ),
* @OA\Response(
* response=404,
* description="Order not found"
* )
* ),
*/
public function deleteOrder()
{
}
}
Controllers/PetController.php
<?php
/**
* @license Apache 2.0
*/
namespace OpenApi\Examples\Specs\Petstore\Attributes\Controllers;
use OpenApi\Attributes as OAT;
use OpenApi\Examples\Specs\Petstore\Attributes\Models\ApiResponse;
use OpenApi\Examples\Specs\Petstore\Attributes\Models\Pet;
use OpenApi\Examples\Specs\Petstore\Attributes\Models\PetRequestBody;
/**
* Class Pet.
*
* @author Donii Sergii <doniysa@gmail.com>
*/
class PetController
{
/**
* Add a new pet to the store.
*/
#[OAT\Post(
path: '/pet',
tags: ['pet'],
operationId: 'addPet',
responses: [
new OAT\Response(
response: 405,
description: 'Invalid input'
),
],
security: [
[
'petstore_auth' => [
'write:pets',
'read:pets',
],
],
],
requestBody: new OAT\RequestBody(
ref: PetRequestBody::class
)
)]
public function addPet()
{
}
/**
* Update an existing pet.
*/
#[OAT\Put(
path: '/pet',
tags: ['pet'],
operationId: 'updatePet',
responses: [
new OAT\Response(
response: 400,
description: 'Invalid ID supplied'
),
new OAT\Response(
response: 404,
description: 'Pet not found'
),
new OAT\Response(
response: 405,
description: 'Validation exception'
),
],
security: [
[
'petstore_auth' => [
'write:pets',
'read:pets',
],
],
],
requestBody: new OAT\RequestBody(
ref: PetRequestBody::class
)
)]
public function updatePet()
{
}
#[OAT\Get(
path: '/pet/findByStatus',
tags: ['pet'],
summary: 'Finds Pets by status',
description: 'Multiple status values can be provided with comma separated string',
operationId: 'findPetsByStatus',
deprecated: true,
parameters: [
new OAT\Parameter(
name: 'status',
in: 'query',
description: 'Status values that needed to be considered for filter',
required: true,
explode: true,
schema: new OAT\Schema(
type: 'string',
enum: ['available', 'pending', 'sold'],
default: 'available'
)
),
],
responses: [
new OAT\Response(
response: 200,
description: 'successful operation',
content: [
new OAT\JsonContent(
type: 'array',
items: new OAT\Items(
ref: Pet::class
)
),
new OAT\XmlContent(
type: 'array',
items: new OAT\Items(
ref: Pet::class
)
),
]
),
new OAT\Response(
response: 400,
description: 'Invalid status value'
),
],
security: [
[
'petstore_auth' => [
'write:pets',
'read:pets',
],
],
],
)]
public function findPetsByStatus()
{
}
#[OAT\Get(
path: '/pet/findByTags',
tags: ['pet'],
summary: 'Finds Pets by tags',
description: 'Muliple tags can be provided with comma separated strings. Use tag1, tag2, tag3 for testing.',
operationId: 'findByTags',
parameters: [
new OAT\Parameter(
name: 'tags',
in: 'query',
description: 'Tags to filter by',
required: true,
explode: true,
schema: new OAT\Schema(
type: 'array',
items: new OAT\Items(
type: 'string'
)
)
),
],
responses: [
new OAT\Response(
response: 200,
description: 'successful operation',
content: [
new OAT\JsonContent(
type: 'array',
items: new OAT\Items(
ref: Pet::class
)
),
new OAT\XmlContent(
type: 'array',
items: new OAT\Items(
ref: Pet::class
)
),
]
),
new OAT\Response(
response: 400,
description: 'Invalid tag value'
),
],
security: [
[
'petstore_auth' => [
'write:pets',
'read:pets',
],
],
],
)]
public function findByTags()
{
}
#[OAT\Get(
path: '/pet/{petId}',
tags: ['pet'],
summary: 'Find pet by ID',
description: 'Returns a single pet',
operationId: 'getPetById',
parameters: [
new OAT\Parameter(
name: 'petId',
in: 'path',
description: 'ID of pet to return',
required: true,
schema: new OAT\Schema(
type: 'integer',
format: 'int64'
)
),
],
responses: [
new OAT\Response(
response: 200,
description: 'successful operation',
content: [
new OAT\JsonContent(
ref: Pet::class
),
new OAT\XmlContent(
ref: Pet::class
),
]
),
new OAT\Response(
response: 400,
description: 'Invalid ID supplier'
),
new OAT\Response(
response: 404,
description: 'Pet not found'
),
],
security: [
[
'api_key' => [
],
],
]
)]
public function getPetById(int $id)
{
}
#[OAT\Post(
path: '/pet/{petId}',
tags: ['pet'],
summary: 'Updates a pet in the store with form data',
operationId: 'updatePetWithForm',
parameters: [
new OAT\Parameter(
name: 'petId',
in: 'path',
description: 'ID of pet that needs to be updated',
required: true,
schema: new OAT\Schema(
type: 'integer',
format: 'int64'
)
),
],
responses: [
new OAT\Response(
response: 405,
description: 'Invalid input'
),
],
security: [
[
'petstore_auth' => [
'write:pets',
'read:pets',
],
],
],
requestBody: new OAT\RequestBody(
description: 'Input data format',
content: new OAT\MediaType(
mediaType: 'application/x-www-form-urlencoded',
schema: new OAT\Schema(
type: 'object',
properties: [
new OAT\Property(
property: 'name',
description: 'Updated name of the pet',
type: 'string'
),
new OAT\Property(
property: 'status',
description: 'Updated status of the pet',
type: 'string'
),
]
)
)
)
)]
public function updatePetWithForm()
{
}
#[OAT\Delete(
path: '/pet/{petId}',
tags: ['pet'],
summary: 'Deletes a pet',
operationId: 'deletePet',
parameters: [
new OAT\Parameter(
name: 'api_key',
in: 'header',
required: false,
schema: new OAT\Schema(
type: 'string'
)
),
new OAT\Parameter(
name: 'petId',
in: 'path',
description: 'Pet id to delete',
required: true,
schema: new OAT\Schema(
type: 'integer',
format: 'int64'
)
),
],
responses: [
new OAT\Response(
response: 400,
description: 'Invalid ID supplied'
),
new OAT\Response(
response: 404,
description: 'Pet not found'
),
],
security: [
[
'petstore_auth' => [
'write:pets',
'read:pets',
],
],
],
)]
public function deletePet()
{
}
#[OAT\Post(
path: '/pet/{petId}/uploadImage',
tags: ['pet'],
summary: 'uploads an image',
operationId: 'uploadFile',
parameters: [
new OAT\Parameter(
name: 'petId',
in: 'path',
description: 'ID of pet to update',
required: true,
schema: new OAT\Schema(
type: 'integer',
format: 'int64',
example: 1
)
),
],
responses: [
new OAT\Response(
response: 200,
description: 'successful operation',
content: new OAT\JsonContent(
ref: ApiResponse::class
)
),
],
security: [
[
'petstore_auth' => [
'write:pets',
'read:pets',
],
],
],
requestBody: new OAT\RequestBody(
description: 'Upload images request body',
content: new OAT\MediaType(
mediaType: 'application/octet-stream',
schema: new OAT\Schema(
type: 'string',
format: 'binary'
)
)
)
)]
public function uploadFile()
{
}
}
<?php
/**
* @license Apache 2.0
*/
namespace OpenApi\Examples\Specs\Petstore\Annotations\Controllers;
use OpenApi\Annotations as OA;
/**
* Class Pet.
*
* @author Donii Sergii <doniysa@gmail.com>
*/
class PetController
{
/**
* Add a new pet to the store.
*
* @OA\Post(
* path="/pet",
* tags={"pet"},
* operationId="addPet",
* @OA\Response(
* response=405,
* description="Invalid input"
* ),
* security={
* {"petstore_auth": {"write:pets", "read:pets"}}
* },
* @OA\RequestBody(ref="#/components/requestBodies/Pet")
* )
*/
public function addPet()
{
}
/**
* Update an existing pet.
*
* @OA\Put(
* path="/pet",
* tags={"pet"},
* operationId="updatePet",
* @OA\Response(
* response=400,
* description="Invalid ID supplied"
* ),
* @OA\Response(
* response=404,
* description="Pet not found"
* ),
* @OA\Response(
* response=405,
* description="Validation exception"
* ),
* security={
* {"petstore_auth": {"write:pets", "read:pets"}}
* },
* @OA\RequestBody(ref="#/components/requestBodies/Pet")
* )
*/
public function updatePet()
{
}
/**
* @OA\Get(
* path="/pet/findByStatus",
* tags={"pet"},
* summary="Finds Pets by status",
* description="Multiple status values can be provided with comma separated string",
* operationId="findPetsByStatus",
* deprecated=true,
* @OA\Parameter(
* name="status",
* in="query",
* description="Status values that needed to be considered for filter",
* required=true,
* explode=true,
* @OA\Schema(
* default="available",
* type="string",
* enum={"available", "pending", "sold"},
* )
* ),
* @OA\Response(
* response=200,
* description="successful operation",
* @OA\JsonContent(
* type="array",
* @OA\Items(ref="#/components/schemas/Pet")
* ),
* @OA\XmlContent(
* type="array",
* @OA\Items(ref="#/components/schemas/Pet")
* )
* ),
* @OA\Response(
* response=400,
* description="Invalid status value"
* ),
* security={
* {"petstore_auth": {"write:pets", "read:pets"}}
* }
* )
*/
public function findPetsByStatus()
{
}
/**
* @OA\Get(
* path="/pet/findByTags",
* tags={"pet"},
* summary="Finds Pets by tags",
* description="Muliple tags can be provided with comma separated strings. Use tag1, tag2, tag3 for testing.",
* operationId="findByTags",
* @OA\Parameter(
* name="tags",
* in="query",
* description="Tags to filter by",
* required=true,
* explode=true,
* @OA\Schema(
* type="array",
* @OA\Items(
* type="string",
* )
* )
* ),
* @OA\Response(
* response=200,
* description="successful operation",
* @OA\JsonContent(
* type="array",
* @OA\Items(ref="#/components/schemas/Pet")
* ),
* @OA\XmlContent(
* type="array",
* @OA\Items(ref="#/components/schemas/Pet")
* )
* ),
* @OA\Response(
* response=400,
* description="Invalid tag value"
* ),
* security={
* {"petstore_auth": {"write:pets", "read:pets"}}
* }
* )
*/
public function findByTags()
{
}
/**
* @OA\Get(
* path="/pet/{petId}",
* tags={"pet"},
* summary="Find pet by ID",
* description="Returns a single pet",
* operationId="getPetById",
* @OA\Parameter(
* name="petId",
* in="path",
* description="ID of pet to return",
* required=true,
* @OA\Schema(
* type="integer",
* format="int64"
* )
* ),
* @OA\Response(
* response=200,
* description="successful operation",
* @OA\JsonContent(ref="#/components/schemas/Pet"),
* @OA\XmlContent(ref="#/components/schemas/Pet"),
* ),
* @OA\Response(
* response=400,
* description="Invalid ID supplier"
* ),
* @OA\Response(
* response=404,
* description="Pet not found"
* ),
* security={
* {"api_key": {}}
* }
* )
*
* @param int $id
*/
public function getPetById($id)
{
}
/**
* @OA\Post(
* path="/pet/{petId}",
* tags={"pet"},
* summary="Updates a pet in the store with form data",
* operationId="updatePetWithForm",
* @OA\Parameter(
* name="petId",
* in="path",
* description="ID of pet that needs to be updated",
* required=true,
* @OA\Schema(
* type="integer",
* format="int64"
* )
* ),
* @OA\Response(
* response=405,
* description="Invalid input"
* ),
* security={
* {"petstore_auth": {"write:pets", "read:pets"}}
* },
* @OA\RequestBody(
* description="Input data format",
* @OA\MediaType(
* mediaType="application/x-www-form-urlencoded",
* @OA\Schema(
* type="object",
* @OA\Property(
* property="name",
* description="Updated name of the pet",
* type="string",
* ),
* @OA\Property(
* property="status",
* description="Updated status of the pet",
* type="string"
* )
* )
* )
* )
* )
*/
public function updatePetWithForm()
{
}
/**
* @OA\Delete(
* path="/pet/{petId}",
* tags={"pet"},
* summary="Deletes a pet",
* operationId="deletePet",
* @OA\Parameter(
* name="api_key",
* in="header",
* required=false,
* @OA\Schema(
* type="string"
* )
* ),
* @OA\Parameter(
* name="petId",
* in="path",
* description="Pet id to delete",
* required=true,
* @OA\Schema(
* type="integer",
* format="int64"
* ),
* ),
* @OA\Response(
* response=400,
* description="Invalid ID supplied",
* ),
* @OA\Response(
* response=404,
* description="Pet not found",
* ),
* security={
* {"petstore_auth": {"write:pets", "read:pets"}}
* },
* )
*/
public function deletePet()
{
}
/**
* @OA\Post(
* path="/pet/{petId}/uploadImage",
* tags={"pet"},
* summary="uploads an image",
* operationId="uploadFile",
* @OA\Parameter(
* name="petId",
* in="path",
* description="ID of pet to update",
* required=true,
* @OA\Schema(
* type="integer",
* format="int64",
* example=1
* )
* ),
* @OA\Response(
* response=200,
* description="successful operation",
* @OA\JsonContent(ref="#/components/schemas/ApiResponse")
* ),
* security={
* {"petstore_auth": {"write:pets", "read:pets"}}
* },
* @OA\RequestBody(
* description="Upload images request body",
* @OA\MediaType(
* mediaType="application/octet-stream",
* @OA\Schema(
* type="string",
* format="binary"
* )
* )
* )
* )
*/
public function uploadFile()
{
}
}
Petstore.php
<?php
/**
* @license Apache 2.0
*/
namespace OpenApi\Examples\Specs\Petstore\Attributes;
use OpenApi\Attributes as OAT;
#[OAT\OpenApi(
info: new OAT\Info(
description: 'This is a sample Petstore server.
You can find out more about Swagger at [http://swagger.io](http://swagger.io)
or on [irc.freenode.net, #swagger](http://swagger.io/irc/).',
version: '1.0.0',
title: 'Swagger Petstore',
termsOfService: 'http://swagger.io/terms/',
contact: new OAT\Contact(email: 'apiteam@swagger.io'),
license: new OAT\License(
name: 'Apache 2.0',
url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
)
),
tags: [
new OAT\Tag(
name: 'pet',
description: 'Everything about your Pets',
externalDocs: new OAT\ExternalDocumentation(
description: 'Find out more',
url: 'http://swagger.io'
)
),
new OAT\Tag(
name: 'store',
description: 'Access to Petstore orders'
),
new OAT\Tag(
name: 'user',
description: 'Operations about user',
externalDocs: new OAT\ExternalDocumentation(
description: 'Find out more about store',
url: 'http://swagger.io'
)
),
],
servers: [
new OAT\Server(
description: 'Petstore API',
url: 'https://petstore.com/1.0.0'
),
],
externalDocs: new OAT\ExternalDocumentation(
description: 'Find out more about Swagger',
url: 'http://swagger.io'
)
)]
class Petstore
{
}
<?php
/**
* @license Apache 2.0
*/
namespace OpenApi\Examples\Specs\Petstore\Annotations;
use OpenApi\Annotations as OA;
/**
* @OA\Info(
* description="This is a sample Petstore server.
You can find out more about Swagger at [http://swagger.io](http://swagger.io)
or on [irc.freenode.net, #swagger](http://swagger.io/irc/).",
* version="1.0.0",
* title="Swagger Petstore",
* termsOfService="http://swagger.io/terms/",
* @OA\Contact(
* email="apiteam@swagger.io"
* ),
* @OA\License(
* name="Apache 2.0",
* url="http://www.apache.org/licenses/LICENSE-2.0.html"
* )
* )
* @OA\Tag(
* name="pet",
* description="Everything about your Pets",
* @OA\ExternalDocumentation(
* description="Find out more",
* url="http://swagger.io"
* )
* )
* @OA\Tag(
* name="store",
* description="Access to Petstore orders",
* )
* @OA\Tag(
* name="user",
* description="Operations about user",
* @OA\ExternalDocumentation(
* description="Find out more about store",
* url="http://swagger.io"
* )
* )
* @OA\Server(
* description="Petstore API",
* url="https://petstore.com/1.0.0"
* )
* @OA\ExternalDocumentation(
* description="Find out more about Swagger",
* url="http://swagger.io"
* )
*/
class Petstore
{
}
Models/Order.php
<?php
/**
* @license Apache 2.0
*/
namespace OpenApi\Examples\Specs\Petstore\Attributes\Models;
use OpenApi\Attributes as OAT;
/**
* Class Order.
*
* @author Donii Sergii <doniysa@gmail.com>
*/
#[OAT\Schema(
description: 'Order model',
title: 'Order model'
)]
class Order
{
#[OAT\Property(
description: 'ID',
title: 'ID',
format: 'int64',
default: 1
)]
private int $id;
#[OAT\Property(
description: 'Pet ID',
title: 'Pet ID',
format: 'int64',
default: 1
)]
private int $petId;
#[OAT\Property(
description: 'Quantity',
title: 'Quantity',
format: 'int32',
default: 12
)]
private int $quantity;
#[OAT\Property(
description: 'Shipping date',
title: 'Shipping date',
format: 'datetime',
type: 'string',
default: '2017-02-02 18:31:45'
)]
private \DateTime $shipDate;
#[OAT\Property(
description: 'Order status',
title: 'Order status',
enum: ['placed', 'approved', 'delivered'],
default: 'placed'
)]
private string $status;
#[OAT\Property(
description: 'Complete status',
title: 'Complete status',
type: 'boolean',
default: false
)]
private bool $complete;
}
<?php
/**
* @license Apache 2.0
*/
namespace OpenApi\Examples\Specs\Petstore\Annotations\Models;
use OpenApi\Annotations as OA;
/**
* Class Order.
*
* @author Donii Sergii <doniysa@gmail.com>
*
* @OA\Schema(
* title="Order model",
* description="Order model",
* )
*/
class Order
{
/**
* @OA\Property(
* format="int64",
* title="ID",
* default=1,
* description="ID",
* )
*
* @var int
*/
private $id;
/**
* @OA\Property(
* default=1,
* format="int64",
* description="Pet ID",
* title="Pet ID",
* )
*
* @var int
*/
private $petId;
/**
* @OA\Property(
* default=12,
* format="int32",
* description="Quantity",
* title="Quantity",
* )
*
* @var int
*/
private $quantity;
/**
* @OA\Property(
* default="2017-02-02 18:31:45",
* format="datetime",
* description="Shipping date",
* title="Shipping date",
* type="string"
* )
*
* @var \DateTime
*/
private $shipDate;
/**
* @OA\Property(
* default="placed",
* title="Order status",
* description="Order status",
* enum={"placed", "approved", "delivered"},
* )
*
* @var string
*/
private $status;
/**
* @OA\Property(
* default=false,
* type="boolean",
* description="Complete status",
* title="Complete status",
* )
*
* @var bool
*/
private $complete;
}
Models/Category.php
<?php
/**
* @license Apache 2.0
*/
namespace OpenApi\Examples\Specs\Petstore\Attributes\Models;
use OpenApi\Attributes as OAT;
/**
* Pets Category.
*
* @author Donii Sergii <doniysa@gmail.com>
*/
#[OAT\Schema(
title: 'Pets Category.',
xml: new OAT\Xml(
name: 'Category'
)
)]
class Category
{
#[OAT\Property(
description: 'ID',
title: 'ID',
format: 'int64'
)]
private int $id;
#[OAT\Property(
description: 'Category name',
title: 'Category name'
)]
private string $name;
}
<?php
/**
* @license Apache 2.0
*/
namespace OpenApi\Examples\Specs\Petstore\Annotations\Models;
use OpenApi\Annotations as OA;
/**
* Pets Category.
*
* @author Donii Sergii <doniysa@gmail.com>
*
* @OA\Schema(
* title="Pets Category.",
* @OA\Xml(
* name="Category"
* )
* )
*/
class Category
{
/**
* @OA\Property(
* title="ID",
* description="ID",
* format="int64",
* )
*
* @var int
*/
private $id;
/**
* @OA\Property(
* title="Category name",
* description="Category name"
* )
*
* @var string
*/
private $name;
}
Models/Tag.php
<?php
/**
* @license Apache 2.0
*/
namespace OpenApi\Examples\Specs\Petstore\Attributes\Models;
use OpenApi\Attributes as OAT;
/**
* Tag.
*
* @author Donii Sergii <doniysa@gmail.com>
*/
#[OAT\Schema(
title: 'Tag',
xml: new OAT\Xml(
name: 'Tag'
)
)]
class Tag
{
#[OAT\Property(
title: 'ID',
description: 'ID',
format: 'int64'
)]
private int $id;
#[OAT\Property(
title: 'Name',
description: 'Name'
)]
private string $name;
}
<?php
/**
* @license Apache 2.0
*/
namespace OpenApi\Examples\Specs\Petstore\Annotations\Models;
use OpenApi\Annotations as OA;
/**
* Tag.
*
* @author Donii Sergii <doniysa@gmail.com>
*
* @OA\Schema(
* title="Tag",
* @OA\Xml(
* name="Tag"
* )
* )
*/
class Tag
{
/**
* @OA\Property(
* format="int64",
* description="ID",
* title="ID"
* )
*
* @var int
*/
private $id;
/**
* @OA\Property(
* description="Name",
* title="Name"
* )
*
* @var string
*/
private $name;
}
Models/UserArrayRequestBody.php
<?php
/**
* @license Apache 2.0
*/
namespace OpenApi\Examples\Specs\Petstore\Attributes\Models;
use OpenApi\Attributes as OAT;
#[OAT\RequestBody(
request: 'UserArray',
description: 'List of user object',
required: true,
content: new OAT\JsonContent(
type: 'array',
items: new OAT\Items(
ref: User::class
)
)
)]
class UserArrayRequestBody
{
}
<?php
/**
* @license Apache 2.0
*/
namespace OpenApi\Examples\Specs\Petstore\Annotations\Models;
use OpenApi\Annotations as OA;
/**
* @OA\RequestBody(
* request="UserArray",
* description="List of user object",
* required=true,
* @OA\JsonContent(
* type="array",
* @OA\Items(ref="#/components/schemas/User")
* )
* )
*/
class UserArrayRequestBody
{
}
Models/User.php
<?php
/**
* @license Apache 2.0
*/
namespace OpenApi\Examples\Specs\Petstore\Attributes\Models;
use OpenApi\Attributes as OAT;
/**
* Class User.
*
* @author Donii Sergii <doniysa@gmail.com>
*/
#[OAT\Schema(
title: 'User model',
description: 'User model'
)]
class User
{
#[OAT\Property(
title: 'ID',
description: 'ID',
format: 'int64'
)]
private int $id;
#[OAT\Property(
title: 'Username',
description: 'Username'
)]
private string $username;
#[OAT\Property(
title: 'First name',
description: 'First name'
)]
private string $firstName;
#[OAT\Property(
title: 'Last name',
description: 'Last name'
)]
private string $lastName;
#[OAT\Property(
title: 'Email',
description: 'Email',
format: 'email'
)]
private string $email;
#[OAT\Property(
title: 'Password',
description: 'Password',
maximum: 255
)]
private string $password;
#[OAT\Property(
title: 'Phone',
description: 'Phone',
format: 'msisdn'
)]
private string $phone;
#[OAT\Property(
title: 'User status',
description: 'User status',
format: 'int32'
)]
private int $userStatus;
}
<?php
/**
* @license Apache 2.0
*/
namespace OpenApi\Examples\Specs\Petstore\Annotations\Models;
use OpenApi\Annotations as OA;
/**
* Class User.
*
* @author Donii Sergii <doniysa@gmail.com>
*
* @OA\Schema(
* title="User model",
* description="User model",
* )
*/
class User
{
/**
* @OA\Property(
* format="int64",
* description="ID",
* title="ID",
* )
*
* @var int
*/
private $id;
/**
* @OA\Property(
* description="Username",
* title="Username",
* )
*
* @var string
*/
private $username;
/**
* @OA\Property(
* description="First name",
* title="First name",
* )
*
* @var string
*/
private $firstName;
/**
* @OA\Property(
* description="Last name",
* title="Last name",
* )
*
* @var string
*/
private $lastName;
/**
* @OA\Property(
* format="email",
* description="Email",
* title="Email",
* )
*
* @var string
*/
private $email;
/**
* @OA\Property(
* description="Password",
* title="Password",
* maximum=255
* )
*
* @var string
*/
private $password;
/**
* @OA\Property(
* format="msisdn",
* description="Phone",
* title="Phone",
* )
*
* @var string
*/
private $phone;
/**
* @OA\Property(
* format="int32",
* description="User status",
* title="User status",
* )
*
* @var int
*/
private $userStatus;
}
Models/PetRequestBody.php
<?php
/**
* @license Apache 2.0
*/
namespace OpenApi\Examples\Specs\Petstore\Attributes\Models;
use OpenApi\Attributes as OAT;
#[OAT\RequestBody(
request: 'Pet',
description: 'Pet object that needs to be added to the store',
required: true,
content: [
new OAT\JsonContent(
ref: Pet::class
),
new OAT\MediaType(
mediaType: 'application/xml',
schema: new OAT\Schema(
ref: Pet::class
)
),
]
)]
class PetRequestBody
{
}
<?php
/**
* @license Apache 2.0
*/
namespace OpenApi\Examples\Specs\Petstore\Annotations\Models;
use OpenApi\Annotations as OA;
/**
* @OA\RequestBody(
* request="Pet",
* description="Pet object that needs to be added to the store",
* required=true,
* @OA\JsonContent(ref="#/components/schemas/Pet"),
* @OA\MediaType(
* mediaType="application/xml",
* @OA\Schema(ref="#/components/schemas/Pet")
* )
* )
*/
class PetRequestBody
{
}
Models/Pet.php
<?php
/**
* @license Apache 2.0
*/
namespace OpenApi\Examples\Specs\Petstore\Attributes\Models;
use OpenApi\Attributes as OAT;
/**
* Class Pet.
*
* @author Donii Sergii <doniysa@gmail.com>
*/
#[OAT\Schema(
description: 'Pet model',
title: 'Pet model',
required: [
'name',
'photoUrls',
],
xml: new OAT\Xml(
name: 'Pet'
)
)]
class Pet
{
#[OAT\Property(
description: 'ID',
title: 'ID',
format: 'int64'
)]
private int $id;
#[OAT\Property(
title: 'Category'
)]
private Category $category;
#[OAT\Property(
description: 'Pet name',
title: 'Pet name',
format: 'int64'
)]
private string $name;
#[OAT\Property(
description: 'Photo urls',
title: 'Photo urls',
xml: new OAT\Xml(
name: 'photoUrl',
wrapped: true
),
items: new OAT\Items(
type: 'string',
default: 'images/image-1.png'
)
)]
private array $photoUrls;
#[OAT\Property(
description: 'Pet tags',
title: 'Pet tags',
xml: new OAT\Xml(
name: 'tag',
wrapped: true
),
items: new OAT\Items(
type: Tag::class
)
)]
/**
* @var array<Tag>
*/
private array $tags;
}
<?php
/**
* @license Apache 2.0
*/
namespace OpenApi\Examples\Specs\Petstore\Annotations\Models;
use OpenApi\Annotations as OA;
/**
* Class Pet.
*
* @author Donii Sergii <doniysa@gmail.com>
*
* @OA\Schema(
* description="Pet model",
* title="Pet model",
* required={"name", "photoUrls"},
* @OA\Xml(
* name="Pet"
* )
* )
*/
class Pet
{
/**
* @OA\Property(
* format="int64",
* description="ID",
* title="ID",
* )
*
* @var int
*/
private $id;
/**
* @OA\Property(
* title="Category",
* )
*
* @var Category
*/
private $category;
/**
* @OA\Property(
* format="int64",
* description="Pet name",
* title="Pet name",
* )
*
* @var string
*/
private $name;
/**
* @OA\Property(
* description="Photo urls",
* title="Photo urls",
* @OA\Xml(
* name="photoUrl",
* wrapped=true
* ),
* @OA\Items(
* type="string",
* default="images/image-1.png"
* )
* )
*
* @var array
*/
private $photoUrls;
/**
* @OA\Property(
* description="Pet tags",
* title="Pet tags",
* @OA\Xml(
* name="tag",
* wrapped=true
* ),
* )
*
* @var Tag[]
*/
private $tags;
}
Models/ApiResponse.php
<?php
/**
* @license Apache 2.0
*/
namespace OpenApi\Examples\Specs\Petstore\Attributes\Models;
use OpenApi\Attributes as OAT;
/**
* Class ApiResponse.
*
* @author Donii Sergii <doniysa@gmail.com>
*/
#[OAT\Schema(
description: 'Api response',
title: 'Api response'
)]
class ApiResponse
{
#[OAT\Property(
description: 'Code',
title: 'Code',
format: 'int32'
)]
private int $code;
#[OAT\Property(
description: 'Type',
title: 'Type'
)]
private string $type;
#[OAT\Property(
description: 'Message',
title: 'Message'
)]
private string $message;
}
<?php
/**
* @license Apache 2.0
*/
namespace OpenApi\Examples\Specs\Petstore\Annotations\Models;
use OpenApi\Annotations as OA;
/**
* Class ApiResponse.
*
* @author Donii Sergii <doniysa@gmail.com>
*
* @OA\Schema(
* description="Api response",
* title="Api response"
* )
*/
class ApiResponse
{
/**
* @OA\Property(
* description="Code",
* title="Code",
* format="int32"
* )
*
* @var int
*/
private $code;
/**
* @OA\Property(
* description="Type",
* title="Type",
* )
*
* @var string
*/
private $type;
/**
* @OA\Property(
* description="Message",
* title="Message"
* )
*
* @var string
*/
private $message;
}
多态性
演示如何使用 Discriminator。
Employee.php
<?php
/**
* @license Apache 2.0
*/
namespace OpenApi\Examples\Specs\Polymorphism\Attributes;
use OpenApi\Attributes as OAT;
#[OAT\Schema(
schema: 'EmployeeResponsible'
)]
final class Employee extends AbstractResponsible
{
#[OAT\Property(
property: 'type'
)]
protected const TYPE = 'Virtual';
#[OAT\Property(
nullable: false
)]
public string $property2;
}
<?php
/**
* @license Apache 2.0
*/
namespace OpenApi\Examples\Specs\Polymorphism\Annotations;
use OpenApi\Annotations as OA;
/**
* @OA\Schema(schema="EmployeeResponsible")
*/
final class Employee extends AbstractResponsible
{
/**
* @OA\Property(property="type")
*/
protected const TYPE = 'Virtual';
/**
* @OA\Property(nullable=false)
*
* @var string
*/
public $property2;
}
Controller.php
<?php
/**
* @license Apache 2.0
*/
namespace OpenApi\Examples\Specs\Polymorphism\Attributes;
use OpenApi\Attributes as OAT;
#[OAT\Info(
title: 'Polymorphism',
description: 'Polymorphism example',
version: '1',
contact: new OAT\Contact(
name: 'Swagger API Team'
)
)]
#[OAT\Tag(
name: 'api',
description: 'API operations'
)]
#[OAT\Server(
url: 'https://example.localhost',
description: 'API server'
)]
class Controller
{
#[OAT\Get(
path: '/test',
operationId: 'test',
description: 'Get test',
tags: ['api'],
responses: [
new OAT\Response(
response: 200,
description: 'Polymorphism',
content: new OAT\JsonContent(
ref: Request::class
)
),
]
)]
public function getProduct($id)
{
}
}
<?php
/**
* @license Apache 2.0
*/
namespace OpenApi\Examples\Specs\Polymorphism\Annotations;
use OpenApi\Annotations as OA;
/**
* @OA\Info(
* title="Polymorphism",
* description="Polymorphism example",
* version="1",
* @OA\Contact(name="Swagger API Team")
* )
* @OA\Tag(
* name="api",
* description="API operations"
* )
* @OA\Server(
* url="https://example.localhost",
* description="API server"
* )
*/
class Controller
{
/**
* @OA\Get(
* path="/test",
* operationId="test",
* description="Get test",
* tags={"api"},
* @OA\Response(
* response="200",
* description="Polymorphism",
* @OA\JsonContent(ref="#/components/schemas/Request")
* )
* )
*/
public function getProduct($id)
{
}
}
Request.php
<?php
/**
* @license Apache 2.0
*/
namespace OpenApi\Examples\Specs\Polymorphism\Attributes;
use OpenApi\Attributes as OAT;
#[OAT\Schema()]
final class Request
{
protected const TYPE = 'employee';
#[OAT\Property()]
public AbstractResponsible $payload;
}
<?php
/**
* @license Apache 2.0
*/
namespace OpenApi\Examples\Specs\Polymorphism\Annotations;
use OpenApi\Annotations as OA;
/**
* @OA\Schema(schema="Request")
*/
final class Request
{
protected const TYPE = 'employee';
/**
* @OA\Property(nullable=false)
*
* @var AbstractResponsible
*/
public $payload;
}
Fl.php
<?php
/**
* @license Apache 2.0
*/
namespace OpenApi\Examples\Specs\Polymorphism\Attributes;
use OpenApi\Attributes as OAT;
#[OAT\Schema(
schema: 'FlResponsible'
)]
final class Fl extends AbstractResponsible
{
public const TYPE = 'fl';
#[OAT\Property()]
public ?string $property3;
}
<?php
/**
* @license Apache 2.0
*/
namespace OpenApi\Examples\Specs\Polymorphism\Annotations;
use OpenApi\Annotations as OA;
/**
* @OA\Schema(schema="FlResponsible")
*/
final class Fl extends AbstractResponsible
{
public const TYPE = 'fl';
/**
* @OA\Property(nullable=true)
*
* @var string
*/
public $property3;
}
AbstractResponsible.php
<?php
/**
* @license Apache 2.0
*/
namespace OpenApi\Examples\Specs\Polymorphism\Attributes;
use OpenApi\Attributes as OAT;
#[OAT\Schema(
schema: 'Responsible',
oneOf: [
new OAT\Schema(ref: Fl::class),
new OAT\Schema(ref: Employee::class),
],
discriminator: new OAT\Discriminator(
propertyName: 'type',
mapping: [
'fl' => Fl::class,
'employee' => Employee::class,
]
)
)]
abstract class AbstractResponsible
{
protected const TYPE = null;
#[OAT\Property(
nullable: false,
enum: ['employee', 'assignee', 'fl']
)]
protected string $type;
public function __construct()
{
$this->type = static::TYPE;
}
}
<?php
/**
* @license Apache 2.0
*/
namespace OpenApi\Examples\Specs\Polymorphism\Annotations;
use OpenApi\Annotations as OA;
/**
* @OA\Schema(
* schema="Responsible",
* @OA\Discriminator(
* propertyName="type",
* mapping={
* "fl": "#/components/schemas/FlResponsible",
* "employee": "#/components/schemas/EmployeeResponsible"
* }
* ),
* oneOf={
* @OA\Schema(ref="#/components/schemas/FlResponsible"),
* @OA\Schema(ref="#/components/schemas/EmployeeResponsible")
* }
* )
*/
abstract class AbstractResponsible
{
protected const TYPE = null;
/**
* @OA\Property(nullable=false, enum={"employee", "assignee", "fl"})
*
* @var string
*/
protected $type;
public function __construct()
{
$this->type = static::TYPE;
}
}