Docs codeblock (#1533)
This commit is contained in:
Martin Rademacher
GitHub
parent
f7faf2392e
commit
423808fcf6
|
|
@ -4,6 +4,7 @@ bin/
|
|||
!bin/openapi
|
||||
composer.lock
|
||||
coverage/
|
||||
docs/.vitepress/cache/
|
||||
docs/.vitepress/dist/
|
||||
docs/node_modules/
|
||||
docs/package-lock.json
|
||||
|
|
|
|||
|
|
@ -59,7 +59,7 @@
|
|||
"require-dev": {
|
||||
"composer/package-versions-deprecated": "^1.11",
|
||||
"doctrine/annotations": "^1.7 || ^2.0",
|
||||
"friendsofphp/php-cs-fixer": "^2.17 || ^3.0",
|
||||
"friendsofphp/php-cs-fixer": "^2.17 || ^3.47.1",
|
||||
"phpstan/phpstan": "^1.6",
|
||||
"phpunit/phpunit": ">=8",
|
||||
"vimeo/psalm": "^4.23"
|
||||
|
|
|
|||
|
|
@ -1,12 +1,12 @@
|
|||
# Cookbook
|
||||
|
||||
## `x-tagGroups`
|
||||
OpenApi has the concept of grouping endpoints using tags. On top of that, some tools
|
||||
([redocly](https://redoc.ly/docs/api-reference-docs/specification-extensions/x-tag-groups/), for example)
|
||||
OpenApi has the concept of grouping endpoints using tags. On top of that, some tools
|
||||
([redocly](https://redoc.ly/docs/api-reference-docs/specification-extensions/x-tag-groups/), for example)
|
||||
support further grouping via the vendor extension `x-tagGroups`.
|
||||
|
||||
```php
|
||||
/**
|
||||
/**
|
||||
* @OA\OpenApi(
|
||||
* x={
|
||||
* "tagGroups"=
|
||||
|
|
@ -14,7 +14,7 @@ support further grouping via the vendor extension `x-tagGroups`.
|
|||
* }
|
||||
* }
|
||||
* )
|
||||
*/
|
||||
*/
|
||||
```
|
||||
|
||||
## Adding examples to `@OA\Response`
|
||||
|
|
@ -142,7 +142,7 @@ An API might have zero or more security schemes. These are defined at the top le
|
|||
* in="header",
|
||||
* securityScheme="api_key"
|
||||
* )
|
||||
*
|
||||
*
|
||||
* @OA\SecurityScheme(
|
||||
* type="oauth2",
|
||||
* securityScheme="petstore_auth",
|
||||
|
|
@ -279,19 +279,19 @@ Unless specified each endpoint needs to declare what security schemes it support
|
|||
to also configure security schemes globally for the whole API.
|
||||
|
||||
This is done on the `@OA\OpenApi` annotations:
|
||||
```php
|
||||
/**
|
||||
* @OA\OpenApi(
|
||||
* security={{"bearerAuth": {}}}
|
||||
* )
|
||||
*
|
||||
* @OA\SecurityScheme(
|
||||
* securityScheme="bearerAuth",
|
||||
* type="http",
|
||||
* scheme="bearer"
|
||||
* )
|
||||
*/
|
||||
```
|
||||
|
||||
<codeblock id="minimal">
|
||||
<template v-slot:an>
|
||||
|
||||
<<< @/snippets/guide/cookbook/default_security_an.php
|
||||
|
||||
</template>
|
||||
<template v-slot:at>
|
||||
|
||||
<<< @/snippets/guide/cookbook/default_security_at.php
|
||||
|
||||
</template>
|
||||
</codeblock>
|
||||
|
||||
## Nested objects
|
||||
Complex, nested data structures are defined by nesting `@OA\Property` annotations inside others (with `type="object"`).
|
||||
|
|
@ -300,7 +300,7 @@ Complex, nested data structures are defined by nesting `@OA\Property` annotation
|
|||
* @OA\Schema(
|
||||
* schema="Profile",
|
||||
* type="object",
|
||||
*
|
||||
*
|
||||
* @OA\Property(
|
||||
* property="Status",
|
||||
* type="string",
|
||||
|
|
@ -350,7 +350,7 @@ A response with either a single or a list of `QualificationHolder`'s.
|
|||
```
|
||||
|
||||
## Reusing responses
|
||||
Global responses are found under `/components/responses` and can be referenced/shared just like schema definitions (models)
|
||||
Global responses are found under `/components/responses` and can be referenced/shared just like schema definitions (models)
|
||||
|
||||
```php
|
||||
/**
|
||||
|
|
@ -361,7 +361,7 @@ Global responses are found under `/components/responses` and can be referenced/s
|
|||
* )
|
||||
*/
|
||||
class ProductResponse {}
|
||||
|
||||
|
||||
// ...
|
||||
|
||||
class ProductController
|
||||
|
|
@ -394,7 +394,7 @@ Using `*/*` as `mediaType` is not possible using annotations.
|
|||
/**
|
||||
* @OA\MediaType(
|
||||
* mediaType="*/*",
|
||||
* @OA\Schema(type="string",format="binary")
|
||||
* @OA\Schema(type="string",format="binary")
|
||||
* )
|
||||
*/
|
||||
```
|
||||
|
|
@ -415,7 +415,7 @@ The API does include basic support for callbacks. However, this needs to be set
|
|||
```php
|
||||
/**
|
||||
* ...
|
||||
*
|
||||
*
|
||||
* callbacks={
|
||||
* "onChange"={
|
||||
* "{$request.query.callbackUrl}"={
|
||||
|
|
@ -435,9 +435,9 @@ The API does include basic support for callbacks. However, this needs to be set
|
|||
* }
|
||||
* }
|
||||
* }
|
||||
*
|
||||
*
|
||||
* ...
|
||||
*
|
||||
*
|
||||
*/
|
||||
```
|
||||
|
||||
|
|
@ -480,7 +480,7 @@ class Book
|
|||
}
|
||||
```
|
||||
|
||||
This works, but is not very convenient.
|
||||
This works, but is not very convenient.
|
||||
|
||||
First, when using custom schema names (`schema: 'user'`), this needs to be taken into account everywhere.
|
||||
Secondly, having to write `ref: '#/components/schemas/user'` is tedious and error-prone.
|
||||
|
|
@ -598,7 +598,7 @@ The corresponding bit of the spec will look like this:
|
|||
```
|
||||
|
||||
`swagger-ui` will show a form that allows to add/remove items (`integer` values in this case) to/from a list
|
||||
and post those values as something like ```?things[]=1&things[]=2&things[]=0```
|
||||
and post those values as something like ```?things[]=1&things[]=2&things[]=0```
|
||||
|
||||
## Custom response classes
|
||||
|
||||
|
|
@ -651,9 +651,9 @@ class Controller
|
|||
```
|
||||
|
||||
::: tip Annotations only?
|
||||
If you are only interested in annotations you canleave out the attribute setup line (`#[\Attribute...`) for `BadRequest`.
|
||||
If you are only interested in annotations you canleave out the attribute setup line (`#[\Attribute...`) for `BadRequest`.
|
||||
|
||||
Furthermore, your custom annotations should extend from the `OpenApi\Annotations` namespace.
|
||||
Furthermore, your custom annotations should extend from the `OpenApi\Annotations` namespace.
|
||||
:::
|
||||
|
||||
## Annotating class constants
|
||||
|
|
@ -685,6 +685,6 @@ components:
|
|||
properties:
|
||||
kind:
|
||||
type: string
|
||||
enum:
|
||||
enum:
|
||||
- Airport
|
||||
```
|
||||
|
|
|
|||
|
|
@ -14,12 +14,12 @@ With the above in mind a minimal API with a single endpoint could look like this
|
|||
<codeblock id="minimal">
|
||||
<template v-slot:an>
|
||||
|
||||
<<< @/snippets/minimal_api_annotations.php
|
||||
<<< @/snippets/minimal_api_an.php
|
||||
|
||||
</template>
|
||||
</template>
|
||||
<template v-slot:at>
|
||||
|
||||
<<< @/snippets/minimal_api_attributes.php
|
||||
<<< @/snippets/minimal_api_at.php
|
||||
|
||||
</template>
|
||||
</codeblock>
|
||||
|
|
@ -29,7 +29,7 @@ with the resulting OpenAPI document like this
|
|||
<<< @/snippets/minimal_api.yaml
|
||||
|
||||
::: warning Code locations
|
||||
Attributes and annotations can be added anywhere on declarations in code as defined by the PHP docs.
|
||||
Attributes and annotations can be added anywhere on declarations in code as defined by the PHP docs.
|
||||
These are limited to the extent of what the PHP Reflection APIs supports.
|
||||
:::
|
||||
|
||||
|
|
|
|||
|
|
@ -25,12 +25,12 @@ Add `swagger-php` annotations or attributes to your source code.
|
|||
<codeblock id="minimal">
|
||||
<template v-slot:an>
|
||||
|
||||
<<< @/snippets/minimal_api_annotations.php
|
||||
<<< @/snippets/minimal_api_an.php
|
||||
|
||||
</template>
|
||||
</template>
|
||||
<template v-slot:at>
|
||||
|
||||
<<< @/snippets/minimal_api_attributes.php
|
||||
<<< @/snippets/minimal_api_at.php
|
||||
|
||||
</template>
|
||||
</codeblock>
|
||||
|
|
|
|||
|
|
@ -26,7 +26,7 @@ These will be ignored by `swagger-php` but can be used for custom processing.
|
|||
|
||||
#### Allowed in
|
||||
---
|
||||
<a href="#additionalproperties">AdditionalProperties</a>, <a href="#components">Components</a>, <a href="#contact">Contact</a>, <a href="#delete">Delete</a>, <a href="#discriminator">Discriminator</a>, <a href="#examples">Examples</a>, <a href="#externaldocumentation">ExternalDocumentation</a>, <a href="#flow">Flow</a>, <a href="#get">Get</a>, <a href="#head">Head</a>, <a href="#header">Header</a>, <a href="#info">Info</a>, <a href="#items">Items</a>, <a href="#jsoncontent">JsonContent</a>, <a href="#license">License</a>, <a href="#link">Link</a>, <a href="#mediatype">MediaType</a>, <a href="#openapi">OpenApi</a>, <a href="#operation">Operation</a>, <a href="#options">Options</a>, <a href="#parameter">Parameter</a>, <a href="#patch">Patch</a>, <a href="#pathitem">PathItem</a>, <a href="#pathparameter">PathParameter</a>, <a href="#post">Post</a>, <a href="#property">Property</a>, <a href="#put">Put</a>, <a href="#requestbody">RequestBody</a>, <a href="#response">Response</a>, <a href="#schema">Schema</a>, <a href="#securityscheme">SecurityScheme</a>, <a href="#server">Server</a>, <a href="#servervariable">ServerVariable</a>, <a href="#tag">Tag</a>, <a href="#trace">Trace</a>, <a href="#xml">Xml</a>, <a href="#xmlcontent">XmlContent</a>
|
||||
<a href="#additionalproperties">AdditionalProperties</a>, <a href="#components">Components</a>, <a href="#contact">Contact</a>, <a href="#delete">Delete</a>, <a href="#discriminator">Discriminator</a>, <a href="#examples">Examples</a>, <a href="#externaldocumentation">ExternalDocumentation</a>, <a href="#flow">Flow</a>, <a href="#get">Get</a>, <a href="#head">Head</a>, <a href="#header">Header</a>, <a href="#info">Info</a>, <a href="#items">Items</a>, <a href="#jsoncontent">JsonContent</a>, <a href="#license">License</a>, <a href="#link">Link</a>, <a href="#mediatype">MediaType</a>, <a href="#openapi">OpenApi</a>, <a href="#operation">Operation</a>, <a href="#options">Options</a>, <a href="#parameter">Parameter</a>, <a href="#patch">Patch</a>, <a href="#pathitem">PathItem</a>, <a href="#pathparameter">PathParameter</a>, <a href="#post">Post</a>, <a href="#property">Property</a>, <a href="#put">Put</a>, <a href="#requestbody">RequestBody</a>, <a href="#response">Response</a>, <a href="#schema">Schema</a>, <a href="#securityscheme">SecurityScheme</a>, <a href="#server">Server</a>, <a href="#servervariable">ServerVariable</a>, <a href="#tag">Tag</a>, <a href="#trace">Trace</a>, <a href="#webhook">Webhook</a>, <a href="#xml">Xml</a>, <a href="#xmlcontent">XmlContent</a>
|
||||
|
||||
## [Components](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Components.php)
|
||||
|
||||
|
|
@ -546,7 +546,7 @@ This is the root document object for the API specification.
|
|||
|
||||
#### Nested elements
|
||||
---
|
||||
<a href="#info">Info</a>, <a href="#server">Server</a>, <a href="#pathitem">PathItem</a>, <a href="#components">Components</a>, <a href="#tag">Tag</a>, <a href="#externaldocumentation">ExternalDocumentation</a>, <a href="#attachable">Attachable</a>
|
||||
<a href="#info">Info</a>, <a href="#server">Server</a>, <a href="#pathitem">PathItem</a>, <a href="#components">Components</a>, <a href="#tag">Tag</a>, <a href="#externaldocumentation">ExternalDocumentation</a>, <a href="#webhook">Webhook</a>, <a href="#attachable">Attachable</a>
|
||||
|
||||
#### Properties
|
||||
---
|
||||
|
|
@ -1232,6 +1232,25 @@ CommonMark syntax MAY be used for rich text representation.</p></dd>
|
|||
<dd><p>No details available.</p></dd>
|
||||
</dl>
|
||||
|
||||
## [Webhook](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Webhook.php)
|
||||
|
||||
Acts like a `PathItem` with the main difference being that it requires `webhook` instead of `path`.
|
||||
|
||||
#### Allowed in
|
||||
---
|
||||
<a href="#openapi">OpenApi</a>
|
||||
|
||||
#### Nested elements
|
||||
---
|
||||
<a href="#get">Get</a>, <a href="#post">Post</a>, <a href="#put">Put</a>, <a href="#delete">Delete</a>, <a href="#patch">Patch</a>, <a href="#trace">Trace</a>, <a href="#head">Head</a>, <a href="#options">Options</a>, <a href="#parameter">Parameter</a>, <a href="#pathparameter">PathParameter</a>, <a href="#server">Server</a>, <a href="#attachable">Attachable</a>
|
||||
|
||||
#### Properties
|
||||
---
|
||||
<dl>
|
||||
<dt><strong>webhook</strong> : <span style="font-family: monospace;">string</span></dt>
|
||||
<dd><p>Key for the webhooks map.</p></dd>
|
||||
</dl>
|
||||
|
||||
## [Xml](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Xml.php)
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -174,7 +174,7 @@ These will be ignored but can be used for custom processing.</p></dd>
|
|||
|
||||
#### Allowed in
|
||||
---
|
||||
<a href="#additionalproperties">AdditionalProperties</a>, <a href="#components">Components</a>, <a href="#contact">Contact</a>, <a href="#delete">Delete</a>, <a href="#discriminator">Discriminator</a>, <a href="#examples">Examples</a>, <a href="#externaldocumentation">ExternalDocumentation</a>, <a href="#flow">Flow</a>, <a href="#get">Get</a>, <a href="#head">Head</a>, <a href="#header">Header</a>, <a href="#info">Info</a>, <a href="#items">Items</a>, <a href="#jsoncontent">JsonContent</a>, <a href="#license">License</a>, <a href="#link">Link</a>, <a href="#mediatype">MediaType</a>, <a href="#openapi">OpenApi</a>, <a href="#operation">Operation</a>, <a href="#options">Options</a>, <a href="#parameter">Parameter</a>, <a href="#patch">Patch</a>, <a href="#pathitem">PathItem</a>, <a href="#pathparameter">PathParameter</a>, <a href="#post">Post</a>, <a href="#property">Property</a>, <a href="#put">Put</a>, <a href="#requestbody">RequestBody</a>, <a href="#response">Response</a>, <a href="#schema">Schema</a>, <a href="#securityscheme">SecurityScheme</a>, <a href="#server">Server</a>, <a href="#servervariable">ServerVariable</a>, <a href="#tag">Tag</a>, <a href="#trace">Trace</a>, <a href="#xml">Xml</a>, <a href="#xmlcontent">XmlContent</a>
|
||||
<a href="#additionalproperties">AdditionalProperties</a>, <a href="#components">Components</a>, <a href="#contact">Contact</a>, <a href="#delete">Delete</a>, <a href="#discriminator">Discriminator</a>, <a href="#examples">Examples</a>, <a href="#externaldocumentation">ExternalDocumentation</a>, <a href="#flow">Flow</a>, <a href="#get">Get</a>, <a href="#head">Head</a>, <a href="#header">Header</a>, <a href="#info">Info</a>, <a href="#items">Items</a>, <a href="#jsoncontent">JsonContent</a>, <a href="#license">License</a>, <a href="#link">Link</a>, <a href="#mediatype">MediaType</a>, <a href="#openapi">OpenApi</a>, <a href="#operation">Operation</a>, <a href="#options">Options</a>, <a href="#parameter">Parameter</a>, <a href="#patch">Patch</a>, <a href="#pathitem">PathItem</a>, <a href="#pathparameter">PathParameter</a>, <a href="#post">Post</a>, <a href="#property">Property</a>, <a href="#put">Put</a>, <a href="#requestbody">RequestBody</a>, <a href="#response">Response</a>, <a href="#schema">Schema</a>, <a href="#securityscheme">SecurityScheme</a>, <a href="#server">Server</a>, <a href="#servervariable">ServerVariable</a>, <a href="#tag">Tag</a>, <a href="#trace">Trace</a>, <a href="#webhook">Webhook</a>, <a href="#xml">Xml</a>, <a href="#xmlcontent">XmlContent</a>
|
||||
|
||||
#### Parameters
|
||||
---
|
||||
|
|
@ -1437,7 +1437,7 @@ These will be ignored but can be used for custom processing.</p></dd>
|
|||
|
||||
#### Nested elements
|
||||
---
|
||||
<a href="#info">Info</a>, <a href="#server">Server</a>, <a href="#pathitem">PathItem</a>, <a href="#components">Components</a>, <a href="#tag">Tag</a>, <a href="#externaldocumentation">ExternalDocumentation</a>, <a href="#attachable">Attachable</a>
|
||||
<a href="#info">Info</a>, <a href="#server">Server</a>, <a href="#pathitem">PathItem</a>, <a href="#components">Components</a>, <a href="#tag">Tag</a>, <a href="#externaldocumentation">ExternalDocumentation</a>, <a href="#webhook">Webhook</a>, <a href="#attachable">Attachable</a>
|
||||
|
||||
#### Parameters
|
||||
---
|
||||
|
|
@ -1476,6 +1476,8 @@ Each tag name in the list must be unique.</p></dd>
|
|||
<dd><p>The available paths and operations for the API.</p></dd>
|
||||
<dt><strong>components</strong> : <span style="font-family: monospace;">OpenApi\Attributes\Components|null</span></dt>
|
||||
<dd><p>An element to hold various components for the specification.</p></dd>
|
||||
<dt><strong>webhooks</strong> : <span style="font-family: monospace;">Webhook[]|null</span></dt>
|
||||
<dd><p>The available webhooks for the API.</p></dd>
|
||||
<dt><strong>x</strong> : <span style="font-family: monospace;">array<string,mixed>|null</span></dt>
|
||||
<dd><p>While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.<br />
|
||||
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions<br />
|
||||
|
|
@ -2878,6 +2880,65 @@ The keys inside the array will be prefixed with `x-`.</p></dd>
|
|||
These will be ignored but can be used for custom processing.</p></dd>
|
||||
</dl>
|
||||
|
||||
## [Webhook](https://github.com/zircote/swagger-php/tree/master/src/Attributes/Webhook.php)
|
||||
|
||||
|
||||
|
||||
#### Allowed in
|
||||
---
|
||||
<a href="#openapi">OpenApi</a>
|
||||
|
||||
#### Nested elements
|
||||
---
|
||||
<a href="#get">Get</a>, <a href="#post">Post</a>, <a href="#put">Put</a>, <a href="#delete">Delete</a>, <a href="#patch">Patch</a>, <a href="#trace">Trace</a>, <a href="#head">Head</a>, <a href="#options">Options</a>, <a href="#parameter">Parameter</a>, <a href="#pathparameter">PathParameter</a>, <a href="#server">Server</a>, <a href="#attachable">Attachable</a>
|
||||
|
||||
#### Parameters
|
||||
---
|
||||
<dl>
|
||||
<dt><strong>webhook</strong> : <span style="font-family: monospace;">string|null</span></dt>
|
||||
<dd><p>Key for the webhooks map.</p></dd>
|
||||
<dt><strong>path</strong> : <span style="font-family: monospace;">string|null</span></dt>
|
||||
<dd><p>Key for the Path Object (OpenApi->paths array).</p></dd>
|
||||
<dt><strong>ref</strong> : <span style="font-family: monospace;">string|class-string|object|null</span></dt>
|
||||
<dd><p>No details available.</p><p><i>See</i>: <a href="https://swagger.io/docs/specification/using-ref/">Using refs</a></p></dd>
|
||||
<dt><strong>summary</strong> : <span style="font-family: monospace;">string|null</span></dt>
|
||||
<dd><p>An optional, string summary, intended to apply to all operations in this path.</p></dd>
|
||||
<dt><strong>description</strong> : <span style="font-family: monospace;">string|null</span></dt>
|
||||
<dd><p>An optional, string description, intended to apply to all operations in this path.</p></dd>
|
||||
<dt><strong>get</strong> : <span style="font-family: monospace;">OpenApi\Attributes\Get|null</span></dt>
|
||||
<dd><p>A definition of a GET operation on this path.</p></dd>
|
||||
<dt><strong>put</strong> : <span style="font-family: monospace;">OpenApi\Attributes\Put|null</span></dt>
|
||||
<dd><p>A definition of a PUT operation on this path.</p></dd>
|
||||
<dt><strong>post</strong> : <span style="font-family: monospace;">OpenApi\Attributes\Post|null</span></dt>
|
||||
<dd><p>A definition of a POST operation on this path.</p></dd>
|
||||
<dt><strong>delete</strong> : <span style="font-family: monospace;">OpenApi\Attributes\Delete|null</span></dt>
|
||||
<dd><p>A definition of a DELETE operation on this path.</p></dd>
|
||||
<dt><strong>options</strong> : <span style="font-family: monospace;">OpenApi\Attributes\Options|null</span></dt>
|
||||
<dd><p>A definition of a OPTIONS operation on this path.</p></dd>
|
||||
<dt><strong>head</strong> : <span style="font-family: monospace;">OpenApi\Attributes\Head|null</span></dt>
|
||||
<dd><p>A definition of a HEAD operation on this path.</p></dd>
|
||||
<dt><strong>patch</strong> : <span style="font-family: monospace;">OpenApi\Attributes\Patch|null</span></dt>
|
||||
<dd><p>A definition of a PATCH operation on this path.</p></dd>
|
||||
<dt><strong>trace</strong> : <span style="font-family: monospace;">OpenApi\Attributes\Trace|null</span></dt>
|
||||
<dd><p>A definition of a TRACE operation on this path.</p></dd>
|
||||
<dt><strong>servers</strong> : <span style="font-family: monospace;">Server[]|null</span></dt>
|
||||
<dd><p>An alternative server array to service all operations in this path.</p></dd>
|
||||
<dt><strong>parameters</strong> : <span style="font-family: monospace;">Parameter[]|null</span></dt>
|
||||
<dd><p>A list of parameters that are applicable for all the operations described under this path.<br />
|
||||
<br />
|
||||
These parameters can be overridden at the operation level, but cannot be removed there.<br />
|
||||
The list must not include duplicated parameters.<br />
|
||||
A unique parameter is defined by a combination of a name and location.<br />
|
||||
The list can use the Reference Object to link to parameters that are defined at the OpenAPI Object's components/parameters.</p></dd>
|
||||
<dt><strong>x</strong> : <span style="font-family: monospace;">array<string,mixed>|null</span></dt>
|
||||
<dd><p>While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.<br />
|
||||
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions<br />
|
||||
The keys inside the array will be prefixed with `x-`.</p></dd>
|
||||
<dt><strong>attachables</strong> : <span style="font-family: monospace;">Attachable[]|null</span></dt>
|
||||
<dd><p>Arbitrary attachables for this annotation.<br />
|
||||
These will be ignored but can be used for custom processing.</p></dd>
|
||||
</dl>
|
||||
|
||||
## [Xml](https://github.com/zircote/swagger-php/tree/master/src/Attributes/Xml.php)
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,18 @@
|
|||
<?php
|
||||
|
||||
use OpenApi\Annotations as OA;
|
||||
|
||||
/**
|
||||
* @OA\OpenApi(
|
||||
* security={{"bearerAuth": {}}}
|
||||
* )
|
||||
*
|
||||
* @OA\SecurityScheme(
|
||||
* securityScheme="bearerAuth",
|
||||
* type="http",
|
||||
* scheme="bearer"
|
||||
* )
|
||||
*/
|
||||
class OpenApi
|
||||
{
|
||||
}
|
||||
|
|
@ -0,0 +1,19 @@
|
|||
<?php
|
||||
|
||||
use OpenApi\Attributes as OAT;
|
||||
|
||||
#[OAT\OpenApi(
|
||||
security: [['bearerAuth' => []]]
|
||||
)]
|
||||
#[OAT\Components(
|
||||
securitySchemes: [
|
||||
new OAT\SecurityScheme(
|
||||
securityScheme: 'bearerAuth',
|
||||
type: 'http',
|
||||
scheme: 'bearer'
|
||||
)
|
||||
]
|
||||
)]
|
||||
class OpenApiSpec
|
||||
{
|
||||
}
|
||||
|
|
@ -8,9 +8,12 @@ use OpenApi\Annotations as OA;
|
|||
* version="0.1"
|
||||
* )
|
||||
*/
|
||||
class OpenApi {}
|
||||
class OpenApi
|
||||
{
|
||||
}
|
||||
|
||||
class MyController {
|
||||
class MyController
|
||||
{
|
||||
|
||||
/**
|
||||
* @OA\Get(
|
||||
|
|
@ -21,7 +24,8 @@ class MyController {
|
|||
* )
|
||||
* )
|
||||
*/
|
||||
public function getResource() {
|
||||
public function getResource()
|
||||
{
|
||||
// ...
|
||||
}
|
||||
}
|
||||
|
|
@ -3,13 +3,21 @@
|
|||
use OpenApi\Attributes as OA;
|
||||
|
||||
#[OA\Info(title: "My First API", version: "0.1")]
|
||||
class OpenApi {}
|
||||
class OpenApi
|
||||
{
|
||||
}
|
||||
|
||||
class MyController {
|
||||
class MyController
|
||||
{
|
||||
|
||||
#[OA\Get(path: '/api/data.json')]
|
||||
#[OA\Response(response: '200', description: 'The data')]
|
||||
public function getResource() {
|
||||
public function getResource()
|
||||
{
|
||||
// ...
|
||||
}
|
||||
}
|
||||
|
||||
class OpenApiSpec
|
||||
{
|
||||
}
|
||||
|
|
@ -16,30 +16,30 @@ use Psr\Log\LoggerInterface;
|
|||
* Contexts are nested to reflect the code/parsing hierarchy. They include useful metadata
|
||||
* which the processors can use to augment the annotations.
|
||||
*
|
||||
* @property string|null $comment The PHP DocComment
|
||||
* @property string|null $filename
|
||||
* @property int|null $line
|
||||
* @property int|null $character
|
||||
* @property string|null $namespace
|
||||
* @property array|null $uses
|
||||
* @property string|null $class
|
||||
* @property string|null $interface
|
||||
* @property string|null $trait
|
||||
* @property string|null $enum
|
||||
* @property array|string|null $extends Interfaces may extend a list of interfaces
|
||||
* @property array|null $implements
|
||||
* @property string|null $method
|
||||
* @property string|null $property
|
||||
* @property string|\ReflectionType|null $type
|
||||
* @property bool|null $static Indicate a static method
|
||||
* @property bool|null $nullable Indicate a nullable value
|
||||
* @property bool|null $generated Indicate the context was generated by a processor or
|
||||
* the serializer
|
||||
* @property Annotations\AbstractAnnotation|null $nested
|
||||
* @property Annotations\AbstractAnnotation[]|null $annotations
|
||||
* @property LoggerInterface|null $logger Guaranteed to be set when using the `Generator`
|
||||
* @property array|null $scanned Details of file scanner when using ReflectionAnalyser
|
||||
* @property string|null $version The OpenAPI version in use
|
||||
* @property string|null $comment The PHP DocComment
|
||||
* @property string|null $filename
|
||||
* @property int|null $line
|
||||
* @property int|null $character
|
||||
* @property string|null $namespace
|
||||
* @property array|null $uses
|
||||
* @property string|null $class
|
||||
* @property string|null $interface
|
||||
* @property string|null $trait
|
||||
* @property string|null $enum
|
||||
* @property array|string|null $extends Interfaces may extend a list of interfaces
|
||||
* @property array|null $implements
|
||||
* @property string|null $method
|
||||
* @property string|null $property
|
||||
* @property string|\ReflectionType|null $type
|
||||
* @property bool|null $static Indicate a static method
|
||||
* @property bool|null $nullable Indicate a nullable value
|
||||
* @property bool|null $generated Indicate the context was generated by a processor or
|
||||
* the serializer
|
||||
* @property OA\AbstractAnnotation|null $nested
|
||||
* @property OA\AbstractAnnotation[]|null $annotations
|
||||
* @property LoggerInterface|null $logger Guaranteed to be set when using the `Generator`
|
||||
* @property array|null $scanned Details of file scanner when using ReflectionAnalyser
|
||||
* @property string|null $version The OpenAPI version in use
|
||||
*/
|
||||
#[\AllowDynamicProperties]
|
||||
class Context
|
||||
|
|
|
|||
|
|
@ -79,7 +79,7 @@ SCHEME;
|
|||
|
||||
$annotations = $this->annotationsFromDocBlockParser($comment);
|
||||
$this->assertCount(1, $annotations);
|
||||
/** @var \OpenApi\Annotations\SecurityScheme $security */
|
||||
/** @var OA\SecurityScheme $security */
|
||||
$security = $annotations[0];
|
||||
$this->assertInstanceOf(OA\SecurityScheme::class, $security);
|
||||
|
||||
|
|
@ -119,7 +119,7 @@ SCHEME;
|
|||
|
||||
$annotations = $this->annotationsFromDocBlockParser($comment);
|
||||
$this->assertCount(1, $annotations);
|
||||
/** @var \OpenApi\Annotations\SecurityScheme $security */
|
||||
/** @var OA\SecurityScheme $security */
|
||||
$security = $annotations[0];
|
||||
|
||||
$this->assertCount(2, $security->flows);
|
||||
|
|
|
|||
|
|
@ -48,7 +48,7 @@ class TypedProperties
|
|||
/**
|
||||
* @OA\Property
|
||||
*/
|
||||
public \OpenApi\Tests\Fixtures\TypedProperties $namespaced;
|
||||
public TypedProperties $namespaced;
|
||||
|
||||
/**
|
||||
* @OA\Property
|
||||
|
|
|
|||
Loading…
Reference in New Issue