diff --git a/docs/reference/annotations.md b/docs/reference/annotations.md
index 3c3435da..9d14d5bc 100644
--- a/docs/reference/annotations.md
+++ b/docs/reference/annotations.md
@@ -1,12 +1,14 @@
-# Annotations
+# Annotation Reference
 
 This page is generated automatically from the `swagger-php` sources.
 
 For improvements head over to [GitHub](https://github.com/zircote/swagger-php) and create a PR ;)
 
+
 In addition to this page, there are also a number of [examples](https://github.com/zircote/swagger-php/tree/master/Examples#readme) which might help you out.
 
-## [AdditionalProperties](https://github.com/zircote/swagger-php/tree/master/src/Annotations/AdditionalProperties.php)
+## Annotations
+### [AdditionalProperties](https://github.com/zircote/swagger-php/tree/master/src/Annotations/AdditionalProperties.php)
 
 
 
@@ -18,7 +20,7 @@ In addition to this page, there are also a number of [examples](https://github.c
 ---
 <a href="#discriminator">Discriminator</a>, <a href="#items">Items</a>, <a href="#property">Property</a>, <a href="#externaldocumentation">ExternalDocumentation</a>, <a href="#xml">Xml</a>, <a href="#additionalproperties">AdditionalProperties</a>, <a href="#attachable">Attachable</a>
 
-## [Attachable](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Attachable.php)
+### [Attachable](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Attachable.php)
 
 A container for custom data to be attached to an annotation.
 
@@ -28,7 +30,7 @@ These will be ignored by `swagger-php` but can be used for custom processing.
 ---
 <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)
+### [Components](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Components.php)
 
 Holds a set of reusable objects for different aspects of the OA.
 
@@ -54,7 +56,7 @@ referenced from properties outside the components object.
 ---
 - [OAI Components Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#components-object)
 
-## [Contact](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Contact.php)
+### [Contact](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Contact.php)
 
 Contact information for the exposed API.
 
@@ -81,7 +83,7 @@ Contact information for the exposed API.
 ---
 - [OAI Contact Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#contact-object)
 
-## [CookieParameter](https://github.com/zircote/swagger-php/tree/master/src/Annotations/CookieParameter.php)
+### [CookieParameter](https://github.com/zircote/swagger-php/tree/master/src/Annotations/CookieParameter.php)
 
 A `@OA\Request` cookie parameter.
 
@@ -100,7 +102,7 @@ A `@OA\Request` cookie parameter.
   <dd><p>This takes 'cookie' as the default location.</p></dd>
 </dl>
 
-## [Delete](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Delete.php)
+### [Delete](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Delete.php)
 
 
 
@@ -119,7 +121,7 @@ A `@OA\Request` cookie parameter.
   <dd><p>No details available.</p></dd>
 </dl>
 
-## [Discriminator](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Discriminator.php)
+### [Discriminator](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Discriminator.php)
 
 The discriminator is a specific object in a schema which is used to inform the consumer of
 the specification of an alternative schema based on the value associated with it.
@@ -149,7 +151,7 @@ On top of this subset, there are extensions provided by this specification to al
 - [OAI Discriminator Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#discriminatorObject)
 - [JSON Schema](http://json-schema.org/)
 
-## [Examples](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Examples.php)
+### [Examples](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Examples.php)
 
 
 
@@ -193,7 +195,7 @@ in JSON or YAML documents.<br />
 The value field and externalValue field are mutually exclusive.</p></dd>
 </dl>
 
-## [ExternalDocumentation](https://github.com/zircote/swagger-php/tree/master/src/Annotations/ExternalDocumentation.php)
+### [ExternalDocumentation](https://github.com/zircote/swagger-php/tree/master/src/Annotations/ExternalDocumentation.php)
 
 Allows referencing an external resource for extended documentation.
 
@@ -218,7 +220,7 @@ Allows referencing an external resource for extended documentation.
 ---
 - [OAI External Documentation Object](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.md#external-documentation-object)
 
-## [Flow](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Flow.php)
+### [Flow](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Flow.php)
 
 Configuration details for a supported OAuth Flow.
 
@@ -259,7 +261,7 @@ A map between the scope name and a short description for it.</p></dd>
 ---
 - [OAI OAuth Flow Object](https://swagger.io/specification/#oauthFlowObject)
 
-## [Get](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Get.php)
+### [Get](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Get.php)
 
 
 
@@ -278,7 +280,7 @@ A map between the scope name and a short description for it.</p></dd>
   <dd><p>No details available.</p></dd>
 </dl>
 
-## [Head](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Head.php)
+### [Head](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Head.php)
 
 
 
@@ -297,7 +299,7 @@ A map between the scope name and a short description for it.</p></dd>
   <dd><p>No details available.</p></dd>
 </dl>
 
-## [Header](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Header.php)
+### [Header](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Header.php)
 
 
 
@@ -339,7 +341,7 @@ If style is used, and if behavior is n/a (cannot be serialized), the value of al
 ---
 - [OAI Header Object](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.md#headerObject).
 
-## [HeaderParameter](https://github.com/zircote/swagger-php/tree/master/src/Annotations/HeaderParameter.php)
+### [HeaderParameter](https://github.com/zircote/swagger-php/tree/master/src/Annotations/HeaderParameter.php)
 
 A `@OA\Request` header parameter.
 
@@ -358,7 +360,7 @@ A `@OA\Request` header parameter.
   <dd><p>This takes 'header' as the default location.</p></dd>
 </dl>
 
-## [Info](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Info.php)
+### [Info](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Info.php)
 
 The object provides metadata about the API.
 
@@ -393,7 +395,7 @@ Must be in the format of an url.</p></dd>
 ---
 - [OAI Info Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#info-object)
 
-## [Items](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Items.php)
+### [Items](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Items.php)
 
 The description of an item in a Schema with type `array`.
 
@@ -405,7 +407,7 @@ The description of an item in a Schema with type `array`.
 ---
 <a href="#discriminator">Discriminator</a>, <a href="#items">Items</a>, <a href="#property">Property</a>, <a href="#externaldocumentation">ExternalDocumentation</a>, <a href="#xml">Xml</a>, <a href="#additionalproperties">AdditionalProperties</a>, <a href="#attachable">Attachable</a>
 
-## [JsonContent](https://github.com/zircote/swagger-php/tree/master/src/Annotations/JsonContent.php)
+### [JsonContent](https://github.com/zircote/swagger-php/tree/master/src/Annotations/JsonContent.php)
 
 Shorthand for a json response.
 
@@ -415,7 +417,7 @@ Use as `@OA\Schema` inside a `Response` and `MediaType`->`'application/json'` wi
 ---
 <a href="#discriminator">Discriminator</a>, <a href="#items">Items</a>, <a href="#property">Property</a>, <a href="#externaldocumentation">ExternalDocumentation</a>, <a href="#additionalproperties">AdditionalProperties</a>, <a href="#examples">Examples</a>, <a href="#attachable">Attachable</a>
 
-## [License](https://github.com/zircote/swagger-php/tree/master/src/Annotations/License.php)
+### [License](https://github.com/zircote/swagger-php/tree/master/src/Annotations/License.php)
 
 License information for the exposed API.
 
@@ -444,7 +446,7 @@ The `url` field is mutually exclusive of the `identifier` field.</p></dd>
 ---
 - [OAI License Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#license-object)
 
-## [Link](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Link.php)
+### [Link](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Link.php)
 
 The Link object represents a possible design-time link for a response.
 
@@ -502,7 +504,7 @@ CommonMark syntax may be used for rich text representation.</p></dd>
 ---
 - [OAI Link Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#link-object)
 
-## [MediaType](https://github.com/zircote/swagger-php/tree/master/src/Annotations/MediaType.php)
+### [MediaType](https://github.com/zircote/swagger-php/tree/master/src/Annotations/MediaType.php)
 
 Each Media Type object provides schema and examples for the media type identified by its key.
 
@@ -540,7 +542,7 @@ application/x-www-form-urlencoded.</p></dd>
 ---
 - [OAI Media Type Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#media-type-object)
 
-## [OpenApi](https://github.com/zircote/swagger-php/tree/master/src/Annotations/OpenApi.php)
+### [OpenApi](https://github.com/zircote/swagger-php/tree/master/src/Annotations/OpenApi.php)
 
 This is the root document object for the API specification.
 
@@ -572,7 +574,7 @@ To make security optional, an empty security requirement `({})` can be included
 ---
 - [OAI OpenApi Object](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.md#openapi-object)
 
-## [Options](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Options.php)
+### [Options](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Options.php)
 
 
 
@@ -591,7 +593,7 @@ To make security optional, an empty security requirement `({})` can be included
   <dd><p>No details available.</p></dd>
 </dl>
 
-## [Parameter](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Parameter.php)
+### [Parameter](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Parameter.php)
 
 Describes a single operation parameter.
 
@@ -701,7 +703,7 @@ This option replaces collectionFormat equal to pipes from OpenAPI 2.0.</p></dd>
 ---
 - [OAA Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameter-object)
 
-## [Patch](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Patch.php)
+### [Patch](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Patch.php)
 
 
 
@@ -720,7 +722,7 @@ This option replaces collectionFormat equal to pipes from OpenAPI 2.0.</p></dd>
   <dd><p>No details available.</p></dd>
 </dl>
 
-## [PathItem](https://github.com/zircote/swagger-php/tree/master/src/Annotations/PathItem.php)
+### [PathItem](https://github.com/zircote/swagger-php/tree/master/src/Annotations/PathItem.php)
 
 Describes the operations available on a single path.
 
@@ -752,7 +754,7 @@ The path itself is still exposed to the documentation viewer, but they will not
 ---
 - [OAI Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#path-item-object)
 
-## [PathParameter](https://github.com/zircote/swagger-php/tree/master/src/Annotations/PathParameter.php)
+### [PathParameter](https://github.com/zircote/swagger-php/tree/master/src/Annotations/PathParameter.php)
 
 A `@OA\Request` path parameter.
 
@@ -773,7 +775,7 @@ A `@OA\Request` path parameter.
   <dd><p>No details available.</p></dd>
 </dl>
 
-## [Post](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Post.php)
+### [Post](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Post.php)
 
 
 
@@ -792,7 +794,7 @@ A `@OA\Request` path parameter.
   <dd><p>No details available.</p></dd>
 </dl>
 
-## [Property](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Property.php)
+### [Property](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Property.php)
 
 
 
@@ -811,7 +813,7 @@ A `@OA\Request` path parameter.
   <dd><p>The key into Schema->properties array.</p></dd>
 </dl>
 
-## [Put](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Put.php)
+### [Put](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Put.php)
 
 
 
@@ -830,7 +832,7 @@ A `@OA\Request` path parameter.
   <dd><p>No details available.</p></dd>
 </dl>
 
-## [QueryParameter](https://github.com/zircote/swagger-php/tree/master/src/Annotations/QueryParameter.php)
+### [QueryParameter](https://github.com/zircote/swagger-php/tree/master/src/Annotations/QueryParameter.php)
 
 A `@OA\Request` query parameter.
 
@@ -849,7 +851,7 @@ A `@OA\Request` query parameter.
   <dd><p>This takes 'query' as the default location.</p></dd>
 </dl>
 
-## [RequestBody](https://github.com/zircote/swagger-php/tree/master/src/Annotations/RequestBody.php)
+### [RequestBody](https://github.com/zircote/swagger-php/tree/master/src/Annotations/RequestBody.php)
 
 Describes a single request body.
 
@@ -885,7 +887,7 @@ Otherwise, the property may be included and its default value is false.</p></dd>
 ---
 - [OAI Request Body Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#requestBodyObject)
 
-## [Response](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Response.php)
+### [Response](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Response.php)
 
 Describes a single response from an API Operation, including design-time,
 static links to operations based on the response.
@@ -917,7 +919,7 @@ CommonMark syntax may be used for rich text representation.</p></dd>
 ---
 - [OAI Response Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#response-object)
 
-## [Schema](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Schema.php)
+### [Schema](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Schema.php)
 
 The definition of input and output data types.
 
@@ -1086,7 +1088,7 @@ defined by this property's value.</p></dd>
 - [OAI Schema Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#schemaObject)
 - [JSON Schema](http://json-schema.org/)
 
-## [SecurityScheme](https://github.com/zircote/swagger-php/tree/master/src/Annotations/SecurityScheme.php)
+### [SecurityScheme](https://github.com/zircote/swagger-php/tree/master/src/Annotations/SecurityScheme.php)
 
 
 
@@ -1127,7 +1129,7 @@ Bearer tokens are usually generated by an authorization server, so this informat
 ---
 - [OAI Security Scheme Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#securitySchemeObject).
 
-## [Server](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Server.php)
+### [Server](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Server.php)
 
 An object representing a server.
 
@@ -1158,7 +1160,7 @@ CommonMark syntax may be used for rich text representation.</p></dd>
 ---
 - [OAI Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#server-object)
 
-## [ServerVariable](https://github.com/zircote/swagger-php/tree/master/src/Annotations/ServerVariable.php)
+### [ServerVariable](https://github.com/zircote/swagger-php/tree/master/src/Annotations/ServerVariable.php)
 
 An object representing a server variable for server URL template substitution.
 
@@ -1195,7 +1197,7 @@ CommonMark syntax MAY be used for rich text representation.</p></dd>
 ---
 - [OAI Server Variable Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#server-variable-object)
 
-## [Tag](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Tag.php)
+### [Tag](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Tag.php)
 
 
 
@@ -1220,7 +1222,7 @@ CommonMark syntax MAY be used for rich text representation.</p></dd>
 ---
 - [OAI Tag Object]( https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.md#tagObject).
 
-## [Trace](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Trace.php)
+### [Trace](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Trace.php)
 
 
 
@@ -1239,7 +1241,7 @@ 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)
+### [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`.
 
@@ -1258,7 +1260,7 @@ Acts like a `PathItem` with the main difference being that it requires `webhook`
   <dd><p>Key for the webhooks map.</p></dd>
 </dl>
 
-## [Xml](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Xml.php)
+### [Xml](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Xml.php)
 
 
 
@@ -1302,7 +1304,7 @@ Default value is false. The definition takes effect only when defined alongside
 ---
 - [OAI XML Object](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.md#xmlObject).
 
-## [XmlContent](https://github.com/zircote/swagger-php/tree/master/src/Annotations/XmlContent.php)
+### [XmlContent](https://github.com/zircote/swagger-php/tree/master/src/Annotations/XmlContent.php)
 
 Shorthand for a xml response.
 
diff --git a/docs/reference/attributes.md b/docs/reference/attributes.md
index 534412bd..a7892e59 100644
--- a/docs/reference/attributes.md
+++ b/docs/reference/attributes.md
@@ -1,12 +1,14 @@
-# Attributes
+# Attribute Reference
 
 This page is generated automatically from the `swagger-php` sources.
 
 For improvements head over to [GitHub](https://github.com/zircote/swagger-php) and create a PR ;)
 
+
 In addition to this page, there are also a number of [examples](https://github.com/zircote/swagger-php/tree/master/Examples#readme) which might help you out.
 
-## [AdditionalProperties](https://github.com/zircote/swagger-php/tree/master/src/Attributes/AdditionalProperties.php)
+## Attributes
+### [AdditionalProperties](https://github.com/zircote/swagger-php/tree/master/src/Attributes/AdditionalProperties.php)
 
 
 
@@ -175,7 +177,7 @@ 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>
 
-## [Attachable](https://github.com/zircote/swagger-php/tree/master/src/Attributes/Attachable.php)
+### [Attachable](https://github.com/zircote/swagger-php/tree/master/src/Attributes/Attachable.php)
 
 
 
@@ -190,7 +192,7 @@ These will be ignored but can be used for custom processing.</p></dd>
   <dd><p>No details available.</p></dd>
 </dl>
 
-## [Components](https://github.com/zircote/swagger-php/tree/master/src/Attributes/Components.php)
+### [Components](https://github.com/zircote/swagger-php/tree/master/src/Attributes/Components.php)
 
 
 
@@ -232,7 +234,7 @@ 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>
 
-## [Contact](https://github.com/zircote/swagger-php/tree/master/src/Attributes/Contact.php)
+### [Contact](https://github.com/zircote/swagger-php/tree/master/src/Attributes/Contact.php)
 
 
 
@@ -262,7 +264,7 @@ 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>
 
-## [CookieParameter](https://github.com/zircote/swagger-php/tree/master/src/Attributes/CookieParameter.php)
+### [CookieParameter](https://github.com/zircote/swagger-php/tree/master/src/Attributes/CookieParameter.php)
 
 
 
@@ -365,7 +367,7 @@ 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>
 
-## [Delete](https://github.com/zircote/swagger-php/tree/master/src/Attributes/Delete.php)
+### [Delete](https://github.com/zircote/swagger-php/tree/master/src/Attributes/Delete.php)
 
 
 
@@ -455,7 +457,7 @@ 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>
 
-## [Discriminator](https://github.com/zircote/swagger-php/tree/master/src/Attributes/Discriminator.php)
+### [Discriminator](https://github.com/zircote/swagger-php/tree/master/src/Attributes/Discriminator.php)
 
 
 
@@ -483,7 +485,7 @@ 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>
 
-## [Examples](https://github.com/zircote/swagger-php/tree/master/src/Attributes/Examples.php)
+### [Examples](https://github.com/zircote/swagger-php/tree/master/src/Attributes/Examples.php)
 
 
 
@@ -534,7 +536,7 @@ 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>
 
-## [ExternalDocumentation](https://github.com/zircote/swagger-php/tree/master/src/Attributes/ExternalDocumentation.php)
+### [ExternalDocumentation](https://github.com/zircote/swagger-php/tree/master/src/Attributes/ExternalDocumentation.php)
 
 
 
@@ -562,7 +564,7 @@ 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>
 
-## [Flow](https://github.com/zircote/swagger-php/tree/master/src/Attributes/Flow.php)
+### [Flow](https://github.com/zircote/swagger-php/tree/master/src/Attributes/Flow.php)
 
 
 
@@ -606,7 +608,7 @@ 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>
 
-## [Get](https://github.com/zircote/swagger-php/tree/master/src/Attributes/Get.php)
+### [Get](https://github.com/zircote/swagger-php/tree/master/src/Attributes/Get.php)
 
 
 
@@ -696,7 +698,7 @@ 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>
 
-## [Head](https://github.com/zircote/swagger-php/tree/master/src/Attributes/Head.php)
+### [Head](https://github.com/zircote/swagger-php/tree/master/src/Attributes/Head.php)
 
 
 
@@ -786,7 +788,7 @@ 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>
 
-## [Header](https://github.com/zircote/swagger-php/tree/master/src/Attributes/Header.php)
+### [Header](https://github.com/zircote/swagger-php/tree/master/src/Attributes/Header.php)
 
 
 
@@ -833,7 +835,7 @@ 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>
 
-## [HeaderParameter](https://github.com/zircote/swagger-php/tree/master/src/Attributes/HeaderParameter.php)
+### [HeaderParameter](https://github.com/zircote/swagger-php/tree/master/src/Attributes/HeaderParameter.php)
 
 
 
@@ -936,7 +938,7 @@ 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>
 
-## [Info](https://github.com/zircote/swagger-php/tree/master/src/Attributes/Info.php)
+### [Info](https://github.com/zircote/swagger-php/tree/master/src/Attributes/Info.php)
 
 
 
@@ -976,7 +978,7 @@ 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>
 
-## [Items](https://github.com/zircote/swagger-php/tree/master/src/Attributes/Items.php)
+### [Items](https://github.com/zircote/swagger-php/tree/master/src/Attributes/Items.php)
 
 
 
@@ -1145,7 +1147,7 @@ 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>
 
-## [JsonContent](https://github.com/zircote/swagger-php/tree/master/src/Attributes/JsonContent.php)
+### [JsonContent](https://github.com/zircote/swagger-php/tree/master/src/Attributes/JsonContent.php)
 
 
 
@@ -1316,7 +1318,7 @@ 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>
 
-## [License](https://github.com/zircote/swagger-php/tree/master/src/Attributes/License.php)
+### [License](https://github.com/zircote/swagger-php/tree/master/src/Attributes/License.php)
 
 
 
@@ -1348,7 +1350,7 @@ 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>
 
-## [Link](https://github.com/zircote/swagger-php/tree/master/src/Attributes/Link.php)
+### [Link](https://github.com/zircote/swagger-php/tree/master/src/Attributes/Link.php)
 
 
 
@@ -1402,7 +1404,7 @@ 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>
 
-## [MediaType](https://github.com/zircote/swagger-php/tree/master/src/Attributes/MediaType.php)
+### [MediaType](https://github.com/zircote/swagger-php/tree/master/src/Attributes/MediaType.php)
 
 
 
@@ -1451,7 +1453,7 @@ 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>
 
-## [OpenApi](https://github.com/zircote/swagger-php/tree/master/src/Attributes/OpenApi.php)
+### [OpenApi](https://github.com/zircote/swagger-php/tree/master/src/Attributes/OpenApi.php)
 
 
 
@@ -1507,7 +1509,7 @@ 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>
 
-## [Options](https://github.com/zircote/swagger-php/tree/master/src/Attributes/Options.php)
+### [Options](https://github.com/zircote/swagger-php/tree/master/src/Attributes/Options.php)
 
 
 
@@ -1597,7 +1599,7 @@ 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>
 
-## [Parameter](https://github.com/zircote/swagger-php/tree/master/src/Attributes/Parameter.php)
+### [Parameter](https://github.com/zircote/swagger-php/tree/master/src/Attributes/Parameter.php)
 
 
 
@@ -1702,7 +1704,7 @@ 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>
 
-## [Patch](https://github.com/zircote/swagger-php/tree/master/src/Attributes/Patch.php)
+### [Patch](https://github.com/zircote/swagger-php/tree/master/src/Attributes/Patch.php)
 
 
 
@@ -1792,7 +1794,7 @@ 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>
 
-## [PathItem](https://github.com/zircote/swagger-php/tree/master/src/Attributes/PathItem.php)
+### [PathItem](https://github.com/zircote/swagger-php/tree/master/src/Attributes/PathItem.php)
 
 
 
@@ -1849,7 +1851,7 @@ 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>
 
-## [PathParameter](https://github.com/zircote/swagger-php/tree/master/src/Attributes/PathParameter.php)
+### [PathParameter](https://github.com/zircote/swagger-php/tree/master/src/Attributes/PathParameter.php)
 
 
 
@@ -1949,7 +1951,7 @@ 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>
 
-## [Post](https://github.com/zircote/swagger-php/tree/master/src/Attributes/Post.php)
+### [Post](https://github.com/zircote/swagger-php/tree/master/src/Attributes/Post.php)
 
 
 
@@ -2039,7 +2041,7 @@ 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>
 
-## [Property](https://github.com/zircote/swagger-php/tree/master/src/Attributes/Property.php)
+### [Property](https://github.com/zircote/swagger-php/tree/master/src/Attributes/Property.php)
 
 
 
@@ -2210,7 +2212,7 @@ 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>
 
-## [Put](https://github.com/zircote/swagger-php/tree/master/src/Attributes/Put.php)
+### [Put](https://github.com/zircote/swagger-php/tree/master/src/Attributes/Put.php)
 
 
 
@@ -2300,7 +2302,7 @@ 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>
 
-## [QueryParameter](https://github.com/zircote/swagger-php/tree/master/src/Attributes/QueryParameter.php)
+### [QueryParameter](https://github.com/zircote/swagger-php/tree/master/src/Attributes/QueryParameter.php)
 
 
 
@@ -2403,7 +2405,7 @@ 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>
 
-## [RequestBody](https://github.com/zircote/swagger-php/tree/master/src/Attributes/RequestBody.php)
+### [RequestBody](https://github.com/zircote/swagger-php/tree/master/src/Attributes/RequestBody.php)
 
 
 
@@ -2447,7 +2449,7 @@ 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>
 
-## [Response](https://github.com/zircote/swagger-php/tree/master/src/Attributes/Response.php)
+### [Response](https://github.com/zircote/swagger-php/tree/master/src/Attributes/Response.php)
 
 
 
@@ -2499,7 +2501,7 @@ 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>
 
-## [Schema](https://github.com/zircote/swagger-php/tree/master/src/Attributes/Schema.php)
+### [Schema](https://github.com/zircote/swagger-php/tree/master/src/Attributes/Schema.php)
 
 
 
@@ -2676,7 +2678,7 @@ 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>
 
-## [SecurityScheme](https://github.com/zircote/swagger-php/tree/master/src/Attributes/SecurityScheme.php)
+### [SecurityScheme](https://github.com/zircote/swagger-php/tree/master/src/Attributes/SecurityScheme.php)
 
 
 
@@ -2722,7 +2724,7 @@ 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>
 
-## [Server](https://github.com/zircote/swagger-php/tree/master/src/Attributes/Server.php)
+### [Server](https://github.com/zircote/swagger-php/tree/master/src/Attributes/Server.php)
 
 
 
@@ -2760,7 +2762,7 @@ 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>
 
-## [ServerVariable](https://github.com/zircote/swagger-php/tree/master/src/Attributes/ServerVariable.php)
+### [ServerVariable](https://github.com/zircote/swagger-php/tree/master/src/Attributes/ServerVariable.php)
 
 
 
@@ -2800,7 +2802,7 @@ 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>
 
-## [Tag](https://github.com/zircote/swagger-php/tree/master/src/Attributes/Tag.php)
+### [Tag](https://github.com/zircote/swagger-php/tree/master/src/Attributes/Tag.php)
 
 
 
@@ -2830,7 +2832,7 @@ 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>
 
-## [Trace](https://github.com/zircote/swagger-php/tree/master/src/Attributes/Trace.php)
+### [Trace](https://github.com/zircote/swagger-php/tree/master/src/Attributes/Trace.php)
 
 
 
@@ -2920,7 +2922,7 @@ 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)
+### [Webhook](https://github.com/zircote/swagger-php/tree/master/src/Attributes/Webhook.php)
 
 
 
@@ -2979,7 +2981,7 @@ 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>
 
-## [Xml](https://github.com/zircote/swagger-php/tree/master/src/Attributes/Xml.php)
+### [Xml](https://github.com/zircote/swagger-php/tree/master/src/Attributes/Xml.php)
 
 
 
@@ -3026,7 +3028,7 @@ 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>
 
-## [XmlContent](https://github.com/zircote/swagger-php/tree/master/src/Attributes/XmlContent.php)
+### [XmlContent](https://github.com/zircote/swagger-php/tree/master/src/Attributes/XmlContent.php)
 
 
 
diff --git a/docs/reference/processors.md b/docs/reference/processors.md
index 1059565b..4629e830 100644
--- a/docs/reference/processors.md
+++ b/docs/reference/processors.md
@@ -1,58 +1,62 @@
-# Processors
+# Processor Reference
 
 This page is generated automatically from the `swagger-php` sources.
 
 For improvements head over to [GitHub](https://github.com/zircote/swagger-php) and create a PR ;)
 
-## [DocBlockDescriptions](https://github.com/zircote/swagger-php/tree/master/src/Processors/DocBlockDescriptions.php)
+
+*Processors are listed in the default order of execution.*
+
+## Processors
+### [DocBlockDescriptions](https://github.com/zircote/swagger-php/tree/master/src/Processors/DocBlockDescriptions.php)
 
 Checks if the annotation has a summary and/or description property
 and uses the text in the comment block (above the annotations) as summary and/or description.
 
 Use `null`, for example: `@Annotation(description=null)`, if you don't want the annotation to have a description.
-## [MergeIntoOpenApi](https://github.com/zircote/swagger-php/tree/master/src/Processors/MergeIntoOpenApi.php)
+### [MergeIntoOpenApi](https://github.com/zircote/swagger-php/tree/master/src/Processors/MergeIntoOpenApi.php)
 
 Merge all @OA\OpenApi annotations into one.
-## [MergeIntoComponents](https://github.com/zircote/swagger-php/tree/master/src/Processors/MergeIntoComponents.php)
+### [MergeIntoComponents](https://github.com/zircote/swagger-php/tree/master/src/Processors/MergeIntoComponents.php)
 
 Merge reusable annotation into @OA\Schemas.
-## [ExpandClasses](https://github.com/zircote/swagger-php/tree/master/src/Processors/ExpandClasses.php)
+### [ExpandClasses](https://github.com/zircote/swagger-php/tree/master/src/Processors/ExpandClasses.php)
 
 Iterate over the chain of ancestors of a schema and:
 - if the ancestor has a schema
 => inherit from the ancestor if it has a schema (allOf) and stop.
 - else
 => merge ancestor properties into the schema.
-## [ExpandInterfaces](https://github.com/zircote/swagger-php/tree/master/src/Processors/ExpandInterfaces.php)
+### [ExpandInterfaces](https://github.com/zircote/swagger-php/tree/master/src/Processors/ExpandInterfaces.php)
 
 Look at all (direct) interfaces for a schema and:
 - merge interfaces annotations/methods into the schema if the interface does not have a schema itself
 - inherit from the interface if it has a schema (allOf).
-## [ExpandTraits](https://github.com/zircote/swagger-php/tree/master/src/Processors/ExpandTraits.php)
+### [ExpandTraits](https://github.com/zircote/swagger-php/tree/master/src/Processors/ExpandTraits.php)
 
 Look at all (direct) traits for a schema and:
 - merge trait annotations/methods/properties into the schema if the trait does not have a schema itself
 - inherit from the trait if it has a schema (allOf).
-## [ExpandEnums](https://github.com/zircote/swagger-php/tree/master/src/Processors/ExpandEnums.php)
+### [ExpandEnums](https://github.com/zircote/swagger-php/tree/master/src/Processors/ExpandEnums.php)
 
 Expands PHP enums.
 
 Determines `schema`, `enum` and `type`.
-## [AugmentSchemas](https://github.com/zircote/swagger-php/tree/master/src/Processors/AugmentSchemas.php)
+### [AugmentSchemas](https://github.com/zircote/swagger-php/tree/master/src/Processors/AugmentSchemas.php)
 
 Use the Schema context to extract useful information and inject that into the annotation.
 
 Merges properties.
-## [AugmentRequestBody](https://github.com/zircote/swagger-php/tree/master/src/Processors/AugmentRequestBody.php)
+### [AugmentRequestBody](https://github.com/zircote/swagger-php/tree/master/src/Processors/AugmentRequestBody.php)
 
 Use the RequestBody context to extract useful information and inject that into the annotation.
-## [AugmentProperties](https://github.com/zircote/swagger-php/tree/master/src/Processors/AugmentProperties.php)
+### [AugmentProperties](https://github.com/zircote/swagger-php/tree/master/src/Processors/AugmentProperties.php)
 
 Use the property context to extract useful information and inject that into the annotation.
-## [BuildPaths](https://github.com/zircote/swagger-php/tree/master/src/Processors/BuildPaths.php)
+### [BuildPaths](https://github.com/zircote/swagger-php/tree/master/src/Processors/BuildPaths.php)
 
 Build the openapi->paths using the detected `@OA\PathItem` and `@OA\Operation` (`@OA\Get`, `@OA\Post`, etc).
-## [AugmentParameters](https://github.com/zircote/swagger-php/tree/master/src/Processors/AugmentParameters.php)
+### [AugmentParameters](https://github.com/zircote/swagger-php/tree/master/src/Processors/AugmentParameters.php)
 
 
 ### Config settings
@@ -62,16 +66,16 @@ Build the openapi->paths using the detected `@OA\PathItem` and `@OA\Operation` (
 </dl>
 
 
-## [AugmentRefs](https://github.com/zircote/swagger-php/tree/master/src/Processors/AugmentRefs.php)
+### [AugmentRefs](https://github.com/zircote/swagger-php/tree/master/src/Processors/AugmentRefs.php)
 
 
-## [MergeJsonContent](https://github.com/zircote/swagger-php/tree/master/src/Processors/MergeJsonContent.php)
+### [MergeJsonContent](https://github.com/zircote/swagger-php/tree/master/src/Processors/MergeJsonContent.php)
 
 Split JsonContent into Schema and MediaType.
-## [MergeXmlContent](https://github.com/zircote/swagger-php/tree/master/src/Processors/MergeXmlContent.php)
+### [MergeXmlContent](https://github.com/zircote/swagger-php/tree/master/src/Processors/MergeXmlContent.php)
 
 Split XmlContent into Schema and MediaType.
-## [OperationId](https://github.com/zircote/swagger-php/tree/master/src/Processors/OperationId.php)
+### [OperationId](https://github.com/zircote/swagger-php/tree/master/src/Processors/OperationId.php)
 
 Generate the OperationId based on the context of the OpenApi annotation.
 ### Config settings
@@ -81,9 +85,9 @@ Generate the OperationId based on the context of the OpenApi annotation.
 </dl>
 
 
-## [CleanUnmerged](https://github.com/zircote/swagger-php/tree/master/src/Processors/CleanUnmerged.php)
+### [CleanUnmerged](https://github.com/zircote/swagger-php/tree/master/src/Processors/CleanUnmerged.php)
 
 
-## [CleanUnusedComponents](https://github.com/zircote/swagger-php/tree/master/src/Processors/CleanUnusedComponents.php)
+### [CleanUnusedComponents](https://github.com/zircote/swagger-php/tree/master/src/Processors/CleanUnusedComponents.php)
 
 
diff --git a/docs/snippets/preamble_annotations.md b/docs/snippets/preamble_annotations.md
new file mode 100644
index 00000000..6d64bd34
--- /dev/null
+++ b/docs/snippets/preamble_annotations.md
@@ -0,0 +1,2 @@
+
+In addition to this page, there are also a number of [examples](https://github.com/zircote/swagger-php/tree/master/Examples#readme) which might help you out.
diff --git a/docs/snippets/preamble_attributes.md b/docs/snippets/preamble_attributes.md
new file mode 100644
index 00000000..6d64bd34
--- /dev/null
+++ b/docs/snippets/preamble_attributes.md
@@ -0,0 +1,2 @@
+
+In addition to this page, there are also a number of [examples](https://github.com/zircote/swagger-php/tree/master/Examples#readme) which might help you out.
diff --git a/docs/snippets/preamble_processors.md b/docs/snippets/preamble_processors.md
new file mode 100644
index 00000000..5f5155ac
--- /dev/null
+++ b/docs/snippets/preamble_processors.md
@@ -0,0 +1,2 @@
+
+*Processors are listed in the default order of execution.*
diff --git a/tools/refgen.php b/tools/refgen.php
index 498a183e..3f0d62eb 100644
--- a/tools/refgen.php
+++ b/tools/refgen.php
@@ -10,7 +10,6 @@
     ob_start();
 
     echo $refgen->preamble($type);
-    echo 'In addition to this page, there are also a number of [examples](https://github.com/zircote/swagger-php/tree/master/Examples#readme) which might help you out.' . PHP_EOL . PHP_EOL;
 
     foreach ($refgen->classesForType($type) as $name => $details) {
         echo $refgen->formatClassHeader($name, $type);
diff --git a/tools/src/Docs/DocGenerator.php b/tools/src/Docs/DocGenerator.php
index 661e1041..6fbb15b9 100644
--- a/tools/src/Docs/DocGenerator.php
+++ b/tools/src/Docs/DocGenerator.php
@@ -25,7 +25,7 @@ public function docPath(string $relativeName): string
     public function formatClassHeader(string $name, string $namespace): string
     {
         return <<< EOT
-## [$name](https://github.com/zircote/swagger-php/tree/master/src/$namespace/$name.php)
+### [$name](https://github.com/zircote/swagger-php/tree/master/src/$namespace/$name.php)
 
 
 EOT;
@@ -33,8 +33,10 @@ public function formatClassHeader(string $name, string $namespace): string
 
     public function preamble(string $type): string
     {
-        return <<< EOT
-# $type
+        $title = rtrim($type, 's');
+
+        $preamble = <<< EOT
+# $title Reference
 
 This page is generated automatically from the `swagger-php` sources.
 
@@ -42,6 +44,20 @@ public function preamble(string $type): string
 
 
 EOT;
+
+        $preambleSnippet = $this->docPath('snippets' . DIRECTORY_SEPARATOR . 'preamble_' . strtolower($type) . '.md');
+
+        if (file_exists($preambleSnippet)) {
+            $preamble .= file_get_contents($preambleSnippet);
+        }
+
+        $preamble .= <<< EOT
+
+## $type
+
+EOT;
+
+        return $preamble;
     }
 
     protected function linkFromMarkup(string $see): ?string