Include annotation / attribute class docblocks in generated reference (…

…#1156)

.php-cs-fixer.dist.php

@@ -3,8 +3,8 @@
 $finder = PhpCsFixer\Finder::create()
     ->path('src')->name('*.php')
     ->path('tests')->name('*.php')
-    //->path('Examples')->name('*.php')
-    ->exclude('tests/Fixtures')
+    ->path('Examples')->name('*.php')
+    //->exclude('tests/Fixtures')
     ->in(__DIR__)
 ;
 

Examples/swagger-spec/petstore-with-external-docs/Models/Pet.php

@@ -2,7 +2,6 @@
 
 namespace OpenApi\Examples\SwaggerSpec\PetstoreWithExternalDocs\Models;
 
-
 /**
  * @OA\Schema(
  *     schema="Pet",

docs/reference/annotations.md

@@ -9,13 +9,23 @@ In addition to this page, there are also a number of [examples](https://github.c
 
 ## [AdditionalProperties](https://github.com/zircote/swagger-php/tree/master/src/Annotations/AdditionalProperties.php)
 
-#### Properties
+### Properties
 ## [Attachable](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Attachable.php)
 
-#### Properties
+A container for custom data to be attached to an annotation.
+
+These will be ignored by `swagger-php` but can be used for custom processing.
+### Properties
 ## [Components](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Components.php)
 
-#### Properties
+Holds a set of reusable objects for different aspects of the OA.
+
+All objects defined within the components object will have no effect on the API unless they are explicitly
+referenced from properties outside the components object.
+
+### References
+- [OAI Components Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#components-object)
+### Properties
 - schemas
 - responses
 - parameters
@@ -27,22 +37,35 @@ In addition to this page, there are also a number of [examples](https://github.c
 - callbacks
 ## [Contact](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Contact.php)
 
-#### Properties
+Contact information for the exposed API.
+
+### References
+- [OAI Contact Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#contact-object)
+### Properties
 - name
 - url
 - email
 ## [Delete](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Delete.php)
 
-#### Properties
+### Properties
 - method
 ## [Discriminator](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Discriminator.php)
 
-#### Properties
+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.
+
+This object is based on the [JSON Schema Specification](http://json-schema.org) and uses a predefined subset of it.
+On top of this subset, there are extensions provided by this specification to allow for more complete documentation.
+
+### References
+- [OAI Discriminator Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#discriminatorObject)
+- [JSON Schema](http://json-schema.org/)
+### Properties
 - propertyName
 - mapping
 ## [Examples](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Examples.php)
 
-#### Properties
+### Properties
 - ref
 - example
 - summary
@@ -51,28 +74,38 @@ In addition to this page, there are also a number of [examples](https://github.c
 - externalValue
 ## [ExternalDocumentation](https://github.com/zircote/swagger-php/tree/master/src/Annotations/ExternalDocumentation.php)
 
-#### Properties
+Allows referencing an external resource for extended documentation.
+
+### References
+- [OAI External Documentation Object](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.md#external-documentation-object)
+### Properties
 - description
 - url
 ## [Flow](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Flow.php)
 
-#### Properties
+Configuration details for a supported OAuth Flow.
+
+### References
+- [OAI OAuth Flow Object](https://swagger.io/specification/#oauthFlowObject)
+### Properties
 - authorizationUrl
 - tokenUrl
 - refreshUrl
 - flow
 - scopes
 ## [Get](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Get.php)
 
-#### Properties
+### Properties
 - method
 ## [Head](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Head.php)
 
-#### Properties
+### Properties
 - method
 ## [Header](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Header.php)
 
-#### Properties
+### References
+- [OAI Header Object](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.md#headerObject)
+### Properties
 - ref
 - header
 - description
@@ -82,7 +115,13 @@ In addition to this page, there are also a number of [examples](https://github.c
 - allowEmptyValue
 ## [Info](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Info.php)
 
-#### Properties
+The object provides metadata about the API.
+
+The metadata may be used by the clients if needed, and may be presented in editing or documentation generation tools for convenience.
+
+### References
+- [OAI Info Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#info-object)
+### Properties
 - title
 - description
 - termsOfService
@@ -91,20 +130,41 @@ In addition to this page, there are also a number of [examples](https://github.c
 - version
 ## [Items](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Items.php)
 
-#### Properties
+The description of an item in a Schema with type "array".
+### Properties
 ## [JsonContent](https://github.com/zircote/swagger-php/tree/master/src/Annotations/JsonContent.php)
 
-#### Properties
+Shorthand for a json response.
+
+Use as an Schema inside a Response and the MediaType "application/json" will be generated.
+### Properties
 - examples
 ## [License](https://github.com/zircote/swagger-php/tree/master/src/Annotations/License.php)
 
-#### Properties
+License information for the exposed API.
+
+### References
+- [OAI License Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#license-object)
+### Properties
 - name
 - identifier
 - url
 ## [Link](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Link.php)
 
-#### Properties
+The Link object represents a possible design-time link for a response.
+
+The presence of a link does not guarantee the caller's ability to successfully invoke it, rather it provides a known
+relationship and traversal mechanism between responses and other operations.
+
+Unlike dynamic links (i.e. links provided in the response payload), the OA linking mechanism does not require
+link information in the runtime response.
+
+For computing links, and providing instructions to execute them, a runtime expression is used for
+accessing values in an operation and using them as parameters while invoking the linked operation.
+
+### References
+- [OAI Link Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#link-object)
+### Properties
 - ref
 - link
 - operationRef
@@ -115,15 +175,23 @@ In addition to this page, there are also a number of [examples](https://github.c
 - server
 ## [MediaType](https://github.com/zircote/swagger-php/tree/master/src/Annotations/MediaType.php)
 
-#### Properties
+Each Media Type Object provides schema and examples for the media type identified by its key.
+
+### References
+- [OAI Media Type Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#media-type-object)
+### Properties
 - mediaType
 - schema
 - example
 - examples
 - encoding
 ## [OpenApi](https://github.com/zircote/swagger-php/tree/master/src/Annotations/OpenApi.php)
 
-#### Properties
+This is the root document object for the API specification.
+
+### References
+- [OAI OpenApi Object](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.md#openapi-object)
+### Properties
 - openapi
 - info
 - servers
@@ -134,11 +202,17 @@ In addition to this page, there are also a number of [examples](https://github.c
 - externalDocs
 ## [Options](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Options.php)
 
-#### Properties
+### Properties
 - method
 ## [Parameter](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Parameter.php)
 
-#### Properties
+Describes a single operation parameter.
+
+A unique parameter is defined by a combination of a name and location.
+
+### References
+- [OAA Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameter-object)
+### Properties
 - ref
 - parameter
 - name
@@ -163,11 +237,18 @@ In addition to this page, there are also a number of [examples](https://github.c
 - deepObject
 ## [Patch](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Patch.php)
 
-#### Properties
+### Properties
 - method
 ## [PathItem](https://github.com/zircote/swagger-php/tree/master/src/Annotations/PathItem.php)
 
-#### Properties
+Describes the operations available on a single path.
+
+A Path Item may be empty, due to ACL constraints.
+The path itself is still exposed to the documentation viewer but they will not know which operations and parameters are available.
+
+### References
+- [OAI Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#path-item-object)
+### Properties
 - ref
 - path
 - summary
@@ -183,32 +264,42 @@ In addition to this page, there are also a number of [examples](https://github.c
 - parameters
 ## [PathParameter](https://github.com/zircote/swagger-php/tree/master/src/Annotations/PathParameter.php)
 
-#### Properties
+A request path parameter.
+### Properties
 - in
 - required
 ## [Post](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Post.php)
 
-#### Properties
+### Properties
 - method
 ## [Property](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Property.php)
 
-#### Properties
+### Properties
 - property
 ## [Put](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Put.php)
 
-#### Properties
+### Properties
 - method
 ## [RequestBody](https://github.com/zircote/swagger-php/tree/master/src/Annotations/RequestBody.php)
 
-#### Properties
+Describes a single request body.
+
+### References
+- [OAI Request Body Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#requestBodyObject)
+### Properties
 - ref
 - request
 - description
 - required
 - content
 ## [Response](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Response.php)
 
-#### Properties
+Describes a single response from an API Operation, including design-time, static links to operations based on the
+response.
+
+### References
+- [OAI Response Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#response-object)
+### Properties
 - ref
 - response
 - description
@@ -217,7 +308,17 @@ In addition to this page, there are also a number of [examples](https://github.c
 - links
 ## [Schema](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Schema.php)
 
-#### Properties
+The definition of input and output data types.
+
+These types can be objects, but also primitives and arrays.
+
+This object is based on the [JSON Schema Specification](http://json-schema.org) and uses a predefined subset of it.
+On top of this subset, there are extensions provided by this specification to allow for more complete documentation.
+
+### References
+- [OAI Schema Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#schemaObject)
+- [JSON Schema](http://json-schema.org/)
+### Properties
 - ref
 - schema
 - title
@@ -264,7 +365,9 @@ In addition to this page, there are also a number of [examples](https://github.c
 - const
 ## [SecurityScheme](https://github.com/zircote/swagger-php/tree/master/src/Annotations/SecurityScheme.php)
 
-#### Properties
+### References
+- [OAI Security Scheme Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#securitySchemeObject)
+### Properties
 - ref
 - securityScheme
 - type
@@ -277,37 +380,52 @@ In addition to this page, there are also a number of [examples](https://github.c
 - openIdConnectUrl
 ## [Server](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Server.php)
 
-#### Properties
+An object representing a Server.
+
+### References
+- [OAI Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#server-object)
+### Properties
 - url
 - description
 - variables
 ## [ServerVariable](https://github.com/zircote/swagger-php/tree/master/src/Annotations/ServerVariable.php)
 
-#### Properties
+An object representing a Server Variable for server URL template substitution.
+
+### References
+- [OAI Server Variable Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#server-variable-object)
+### Properties
 - serverVariable
 - enum
 - default
 - variables
 - description
 ## [Tag](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Tag.php)
 
-#### Properties
+### References
+- [OAI Tag Object]( https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.md#tagObject)
+### Properties
 - name
 - description
 - externalDocs
 ## [Trace](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Trace.php)
 
-#### Properties
+### Properties
 - method
 ## [Xml](https://github.com/zircote/swagger-php/tree/master/src/Annotations/Xml.php)
 
-#### Properties
+### References
+- [OAI XML Object](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.md#xmlObject)
+### Properties
 - name
 - namespace
 - prefix
 - attribute
 - wrapped
 ## [XmlContent](https://github.com/zircote/swagger-php/tree/master/src/Annotations/XmlContent.php)
 
-#### Properties
+Shorthand for a xml response.
+
+Use as an Schema inside a Response and the MediaType "application/xml" will be generated.
+### Properties
 - examples