Docs codeblock (#1533)

.gitignore

@@ -4,6 +4,7 @@ bin/
 !bin/openapi
 composer.lock
 coverage/
+docs/.vitepress/cache/
 docs/.vitepress/dist/
 docs/node_modules/
 docs/package-lock.json

composer.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"

docs/guide/cookbook.md

@@ -1,20 +1,20 @@
 # 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"=
  *           {{"name"="User Management", "tags"={"Users", "API keys", "Admin"}}
  *       }
  *   }
  * )
- */ 
+ */
 ```
 
 ## 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
 ```

docs/guide/required-elements.md

@@ -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.
 :::
 

docs/index.md

@@ -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>

docs/reference/annotations.md

@@ -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)
 
 

docs/reference/attributes.md

@@ -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&lt;string,mixed&gt;|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&lt;string,mixed&gt;|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)
 
 

docs/snippets/guide/cookbook/default_security_an.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
+{
+}

docs/snippets/guide/cookbook/default_security_at.php

@@ -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
+{
+}