Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Better documentation for annotations/attributes #1441

Merged
merged 4 commits into from
Apr 19, 2023
Merged

Better documentation for annotations/attributes #1441

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
6e42c92
improved documentation for annotations/attributes
Apr 14, 2023
9ae3719
update the 'in' attribute description for children of the Parameter C…
Apr 14, 2023
abf3d31
run `composer cs`
Apr 14, 2023
c959d19
separated summary from description
Apr 17, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
72 changes: 45 additions & 27 deletions docs/reference/annotations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -97,7 +97,7 @@ A `@OA\Request` cookie parameter.
---
<dl>
<dt><strong>in</strong></dt>
<dd><p>No details available.</p></dd>
<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)
Expand Down Expand Up @@ -165,7 +165,7 @@ On top of this subset, there are extensions provided by this specification to al
---
<dl>
<dt><strong>ref</strong> : <span style="font-family: monospace;">string|class-string|object</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>
<dd><p>The relative or absolute path to an example.</p><p><i>See</i>: <a href="https://swagger.io/docs/specification/using-ref/">Using refs</a></p></dd>
<dt><strong>example</strong> : <span style="font-family: monospace;">string</span></dt>
<dd><p>The key into `#/components/examples`.</p></dd>
<dt><strong>summary</strong> : <span style="font-family: monospace;">string</span></dt>
Expand Down Expand Up @@ -313,7 +313,7 @@ A map between the scope name and a short description for it.</p></dd>
---
<dl>
<dt><strong>ref</strong> : <span style="font-family: monospace;">string|class-string|object</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>
<dd><p>The relative or absolute path to the endpoint.</p><p><i>See</i>: <a href="https://swagger.io/docs/specification/using-ref/">Using refs</a></p></dd>
<dt><strong>header</strong> : <span style="font-family: monospace;">string</span></dt>
<dd><p>No details available.</p></dd>
<dt><strong>description</strong> : <span style="font-family: monospace;">string</span></dt>
Expand Down Expand Up @@ -355,7 +355,7 @@ A `@OA\Request` header parameter.
---
<dl>
<dt><strong>in</strong></dt>
<dd><p>No details available.</p></dd>
<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)
Expand Down Expand Up @@ -609,7 +609,7 @@ A unique parameter is defined by a combination of a name and location.
---
<dl>
<dt><strong>ref</strong> : <span style="font-family: monospace;">string|class-string|object</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>
<dd><p>The relative or absolute path to the endpoint.</p><p><i>See</i>: <a href="https://swagger.io/docs/specification/using-ref/">Using refs</a></p></dd>
<dt><strong>parameter</strong> : <span style="font-family: monospace;">string</span></dt>
<dd><p>The key into <code>Components::parameters</code> or <code>PathItem::parameters</code> array.</p></dd>
<dt><strong>name</strong> : <span style="font-family: monospace;">string</span></dt>
Expand Down Expand Up @@ -768,7 +768,7 @@ A `@OA\Request` path parameter.
---
<dl>
<dt><strong>in</strong></dt>
<dd><p>No details available.</p></dd>
<dd><p>This takes 'path' as the default location.</p></dd>
<dt><strong>required</strong></dt>
<dd><p>No details available.</p></dd>
</dl>
Expand Down Expand Up @@ -846,7 +846,7 @@ A `@OA\Request` query parameter.
---
<dl>
<dt><strong>in</strong></dt>
<dd><p>No details available.</p></dd>
<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)
Expand All @@ -865,7 +865,7 @@ Describes a single request body.
---
<dl>
<dt><strong>ref</strong> : <span style="font-family: monospace;">string|class-string|object</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>
<dd><p>The relative or absolute path to a request body.</p><p><i>See</i>: <a href="https://swagger.io/docs/specification/using-ref/">Using refs</a></p></dd>
<dt><strong>request</strong> : <span style="font-family: monospace;">string</span></dt>
<dd><p>Request body model name.</p></dd>
<dt><strong>description</strong> : <span style="font-family: monospace;">string</span></dt>
Expand Down Expand Up @@ -902,7 +902,7 @@ static links to operations based on the response.
---
<dl>
<dt><strong>ref</strong> : <span style="font-family: monospace;">string|class-string|object</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>
<dd><p>The relative or absolute path to a response.</p><p><i>See</i>: <a href="https://swagger.io/docs/specification/using-ref/">Using refs</a></p></dd>
<dt><strong>response</strong> : <span style="font-family: monospace;">string|int</span></dt>
<dd><p>The key into Operations->responses array.<br />
<br />
Expand Down Expand Up @@ -938,7 +938,7 @@ On top of this subset, there are extensions provided by this specification to al
---
<dl>
<dt><strong>ref</strong> : <span style="font-family: monospace;">string|class-string|object</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>
<dd><p>The relative or absolute path to the endpoint.</p><p><i>See</i>: <a href="https://swagger.io/docs/specification/using-ref/">Using refs</a></p></dd>
<dt><strong>schema</strong> : <span style="font-family: monospace;">string</span></dt>
<dd><p>The key into Components->schemas array.</p></dd>
<dt><strong>title</strong> : <span style="font-family: monospace;">string</span></dt>
Expand All @@ -948,21 +948,23 @@ Preferably short; use <code>description</code> for more details.</p></dd>
<dt><strong>description</strong> : <span style="font-family: monospace;">string</span></dt>
<dd><p>A description will provide explanation about the purpose of the instance described by this schema.</p></dd>
<dt><strong>maxProperties</strong> : <span style="font-family: monospace;">int</span></dt>
<dd><p>An object instance is valid against "maxProperties" if its number of properties is less than, or equal to, the<br />
value of this property.</p></dd>
<dd><p>The maximum number of properties allowed in an object instance.<br />
An object instance is valid against this property if its number of properties is less than, or equal to, the value of this attribute.</p></dd>
<dt><strong>minProperties</strong> : <span style="font-family: monospace;">int</span></dt>
<dd><p>An object instance is valid against "minProperties" if its number of properties is greater than, or equal to,<br />
the value of this property.</p></dd>
<dd><p>The minimum number of properties allowed in an object instance.<br />
An object instance is valid against this property if its number of properties is greater than, or equal to, the value of this attribute.</p></dd>
<dt><strong>required</strong> : <span style="font-family: monospace;">string[]</span></dt>
<dd><p>An object instance is valid against this property if its property set contains all elements in this property's<br />
array value.</p></dd>
<dt><strong>type</strong> : <span style="font-family: monospace;">string</span></dt>
<dd><p>The type of the schema/property. The value MUST be one of "string", "number", "integer", "boolean", "array" or<br />
"object".</p></dd>
<dd><p>The type of the schema/property.<br />
<br />
The value MUST be one of "string", "number", "integer", "boolean", "array" or "object".</p></dd>
<dt><strong>format</strong> : <span style="font-family: monospace;">string</span></dt>
<dd><p>The extending format for the previously mentioned type. See Data Type Formats for further details.</p></dd>
<dt><strong>collectionFormat</strong> : <span style="font-family: monospace;">string</span></dt>
<dd><p>Determines the format of the array if type array is used.<br />
<br />
Possible values are:<br />
- csv: comma separated values foo,bar.<br />
- ssv: space separated values foo bar.<br />
Expand All @@ -974,27 +976,43 @@ Default value is csv.</p></dd>
<dt><strong>default</strong> : <span style="font-family: monospace;">mixed</span></dt>
<dd><p>Sets a default value to the parameter. The type of the value depends on the defined type.</p><p><i>See</i>: <a href="http://json-schema.org/latest/json-schema-validation.html#anchor101">JSON schema validation</a></p></dd>
<dt><strong>maximum</strong> : <span style="font-family: monospace;">int|float</span></dt>
<dd><p>No details available.</p><p><i>See</i>: <a href="http://json-schema.org/latest/json-schema-validation.html#anchor17">JSON schema validation</a></p></dd>
<dd><p>The maximum value allowed for a numeric property. This value must be a number.</p><p><i>See</i>: <a href="http://json-schema.org/latest/json-schema-validation.html#anchor17">JSON schema validation</a></p></dd>
<dt><strong>exclusiveMaximum</strong> : <span style="font-family: monospace;">bool</span></dt>
<dd><p>No details available.</p><p><i>See</i>: <a href="http://json-schema.org/latest/json-schema-validation.html#anchor17">JSON schema validation</a></p></dd>
<dd><p>A boolean indicating whether the maximum value is excluded from the set of valid values.<br />
<br />
When set to true, the maximum value is excluded, and when false or not specified, it is included.</p><p><i>See</i>: <a href="http://json-schema.org/latest/json-schema-validation.html#anchor17">JSON schema validation</a></p></dd>
<dt><strong>minimum</strong> : <span style="font-family: monospace;">int|float</span></dt>
<dd><p>No details available.</p><p><i>See</i>: <a href="http://json-schema.org/latest/json-schema-validation.html#anchor21">JSON schema validation</a></p></dd>
<dd><p>The minimum value allowed for a numeric property. This value must be a number.</p><p><i>See</i>: <a href="http://json-schema.org/latest/json-schema-validation.html#anchor21">JSON schema validation</a></p></dd>
<dt><strong>exclusiveMinimum</strong> : <span style="font-family: monospace;">bool</span></dt>
<dd><p>No details available.</p><p><i>See</i>: <a href="http://json-schema.org/latest/json-schema-validation.html#anchor21">JSON schema validation</a></p></dd>
<dd><p>A boolean indicating whether the minimum value is excluded from the set of valid values.<br />
<br />
When set to true, the minimum value is excluded, and when false or not specified, it is included.</p><p><i>See</i>: <a href="http://json-schema.org/latest/json-schema-validation.html#anchor21">JSON schema validation</a></p></dd>
<dt><strong>maxLength</strong> : <span style="font-family: monospace;">int</span></dt>
<dd><p>No details available.</p><p><i>See</i>: <a href="http://json-schema.org/latest/json-schema-validation.html#anchor26">JSON schema validation</a></p></dd>
<dd><p>The maximum length of a string property.<br />
<br />
A string instance is valid against this property if its length is less than, or equal to, the value of this attribute.</p><p><i>See</i>: <a href="http://json-schema.org/latest/json-schema-validation.html#anchor26">JSON schema validation</a></p></dd>
<dt><strong>minLength</strong> : <span style="font-family: monospace;">int</span></dt>
<dd><p>No details available.</p><p><i>See</i>: <a href="http://json-schema.org/latest/json-schema-validation.html#anchor29">JSON schema validation</a></p></dd>
<dd><p>The minimum length of a string property.<br />
<br />
A string instance is valid against this property if its length is greater than, or equal to, the value of this attribute.</p><p><i>See</i>: <a href="http://json-schema.org/latest/json-schema-validation.html#anchor29">JSON schema validation</a></p></dd>
<dt><strong>pattern</strong> : <span style="font-family: monospace;">string</span></dt>
<dd><p>A string instance is considered valid if the regular expression matches the instance successfully.</p></dd>
<dt><strong>maxItems</strong> : <span style="font-family: monospace;">int</span></dt>
<dd><p>No details available.</p><p><i>See</i>: <a href="http://json-schema.org/latest/json-schema-validation.html#anchor42">JSON schema validation</a></p></dd>
<dd><p>The maximum number of items allowed in an array property.<br />
<br />
An array instance is valid against this property if its number of items is less than, or equal to, the value of this attribute.</p><p><i>See</i>: <a href="http://json-schema.org/latest/json-schema-validation.html#anchor42">JSON schema validation</a></p></dd>
<dt><strong>minItems</strong> : <span style="font-family: monospace;">int</span></dt>
<dd><p>No details available.</p><p><i>See</i>: <a href="http://json-schema.org/latest/json-schema-validation.html#anchor45">JSON schema validation</a></p></dd>
<dd><p>The minimum number of items allowed in an array property.<br />
<br />
An array instance is valid against this property if its number of items is greater than, or equal to, the value of this attribute.</p><p><i>See</i>: <a href="http://json-schema.org/latest/json-schema-validation.html#anchor45">JSON schema validation</a></p></dd>
<dt><strong>uniqueItems</strong> : <span style="font-family: monospace;">bool</span></dt>
<dd><p>No details available.</p><p><i>See</i>: <a href="http://json-schema.org/latest/json-schema-validation.html#anchor49">JSON schema validation</a></p></dd>
<dd><p>A boolean value indicating whether all items in an array property must be unique.<br />
<br />
If this attribute is set to true, then all items in the array must be unique.</p><p><i>See</i>: <a href="http://json-schema.org/latest/json-schema-validation.html#anchor49">JSON schema validation</a></p></dd>
<dt><strong>enum</strong> : <span style="font-family: monospace;">string[]|int[]|float[]|\UnitEnum[]|class-string</span></dt>
<dd><p>No details available.</p><p><i>See</i>: <a href="http://json-schema.org/latest/json-schema-validation.html#anchor76">JSON schema validation</a></p></dd>
<dd><p>A collection of allowable values for a property.<br />
<br />
A property instance is valid against this attribute if its value is one of the values specified in this collection.</p><p><i>See</i>: <a href="http://json-schema.org/latest/json-schema-validation.html#anchor76">JSON schema validation</a></p></dd>
<dt><strong>multipleOf</strong> : <span style="font-family: monospace;">int|float</span></dt>
<dd><p>A numeric instance is valid against "multipleOf" if the result of the division of the instance by this<br />
property's value is an integer.</p></dd>
Expand Down Expand Up @@ -1072,7 +1090,7 @@ defined by this property's value.</p></dd>
---
<dl>
<dt><strong>ref</strong> : <span style="font-family: monospace;">string|class-string|object</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>
<dd><p>The relative or absolute path to a security scheme.</p><p><i>See</i>: <a href="https://swagger.io/docs/specification/using-ref/">Using refs</a></p></dd>
<dt><strong>securityScheme</strong> : <span style="font-family: monospace;">string</span></dt>
<dd><p>The key into OpenApi->security array.</p></dd>
<dt><strong>type</strong> : <span style="font-family: monospace;">string</span></dt>
Expand Down
Loading