Use Annotation property docblocks to document Attribute constructor parameters (#1439)
This commit is contained in:
Martin Rademacher
GitHub
parent
a009c24560
commit
bf5ab27a57
|
|
@ -164,7 +164,7 @@ On top of this subset, there are extensions provided by this specification to al
|
|||
#### Properties
|
||||
---
|
||||
<dl>
|
||||
<dt><strong>ref</strong> : <span style="font-family: monospace;">string|object</span></dt>
|
||||
<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>
|
||||
<dt><strong>example</strong> : <span style="font-family: monospace;">string</span></dt>
|
||||
<dd><p>The key into `#/components/examples`.</p></dd>
|
||||
|
|
@ -312,7 +312,7 @@ A map between the scope name and a short description for it.</p></dd>
|
|||
#### Properties
|
||||
---
|
||||
<dl>
|
||||
<dt><strong>ref</strong> : <span style="font-family: monospace;">string|object</span></dt>
|
||||
<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>
|
||||
<dt><strong>header</strong> : <span style="font-family: monospace;">string</span></dt>
|
||||
<dd><p>No details available.</p></dd>
|
||||
|
|
@ -468,7 +468,7 @@ accessing values in an operation and using them as parameters while invoking the
|
|||
#### Properties
|
||||
---
|
||||
<dl>
|
||||
<dt><strong>ref</strong> : <span style="font-family: monospace;">string|object</span></dt>
|
||||
<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>
|
||||
<dt><strong>link</strong> : <span style="font-family: monospace;">string</span></dt>
|
||||
<dd><p>The key into MediaType->links array.</p></dd>
|
||||
|
|
@ -608,7 +608,7 @@ A unique parameter is defined by a combination of a name and location.
|
|||
#### Properties
|
||||
---
|
||||
<dl>
|
||||
<dt><strong>ref</strong> : <span style="font-family: monospace;">string|object</span></dt>
|
||||
<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>
|
||||
<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>
|
||||
|
|
@ -738,12 +738,14 @@ The path itself is still exposed to the documentation viewer, but they will not
|
|||
#### Properties
|
||||
---
|
||||
<dl>
|
||||
<dt><strong>ref</strong> : <span style="font-family: monospace;">string|object</span></dt>
|
||||
<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>
|
||||
<dt><strong>path</strong> : <span style="font-family: monospace;">string</span></dt>
|
||||
<dd><p>Key for the Path Object (OpenApi->paths array).</p></dd>
|
||||
<dt><strong>summary</strong> : <span style="font-family: monospace;">string</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</span></dt>
|
||||
<dd><p>An optional, string description, intended to apply to all operations in this path.</p></dd>
|
||||
<dt><strong>path</strong> : <span style="font-family: monospace;">string</span></dt>
|
||||
<dd><p>Key for the Path Object (OpenApi->paths array).</p></dd>
|
||||
</dl>
|
||||
|
||||
#### Reference
|
||||
|
|
@ -862,7 +864,7 @@ Describes a single request body.
|
|||
#### Properties
|
||||
---
|
||||
<dl>
|
||||
<dt><strong>ref</strong> : <span style="font-family: monospace;">string|object</span></dt>
|
||||
<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>
|
||||
<dt><strong>request</strong> : <span style="font-family: monospace;">string</span></dt>
|
||||
<dd><p>Request body model name.</p></dd>
|
||||
|
|
@ -899,7 +901,7 @@ static links to operations based on the response.
|
|||
#### Properties
|
||||
---
|
||||
<dl>
|
||||
<dt><strong>ref</strong> : <span style="font-family: monospace;">string|object</span></dt>
|
||||
<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>
|
||||
<dt><strong>response</strong> : <span style="font-family: monospace;">string|int</span></dt>
|
||||
<dd><p>The key into Operations->responses array.<br />
|
||||
|
|
@ -935,7 +937,7 @@ On top of this subset, there are extensions provided by this specification to al
|
|||
#### Properties
|
||||
---
|
||||
<dl>
|
||||
<dt><strong>ref</strong> : <span style="font-family: monospace;">string|object</span></dt>
|
||||
<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>
|
||||
<dt><strong>schema</strong> : <span style="font-family: monospace;">string</span></dt>
|
||||
<dd><p>The key into Components->schemas array.</p></dd>
|
||||
|
|
@ -1069,7 +1071,7 @@ defined by this property's value.</p></dd>
|
|||
#### Properties
|
||||
---
|
||||
<dl>
|
||||
<dt><strong>ref</strong> : <span style="font-family: monospace;">string|object</span></dt>
|
||||
<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>
|
||||
<dt><strong>securityScheme</strong> : <span style="font-family: monospace;">string</span></dt>
|
||||
<dd><p>The key into OpenApi->security array.</p></dd>
|
||||
|
|
|
|||
File diff suppressed because it is too large
Load Diff
|
|
@ -61,7 +61,7 @@ Build the openapi->paths using the detected `@OA\PathItem` and `@OA\Operation` (
|
|||
|
||||
## [AugmentRefs](https://github.com/zircote/swagger-php/tree/master/src/Processors/AugmentRefs.php)
|
||||
|
||||
Update refs broken due to `allOf` augmenting.
|
||||
|
||||
## [MergeJsonContent](https://github.com/zircote/swagger-php/tree/master/src/Processors/MergeJsonContent.php)
|
||||
|
||||
Split JsonContent into Schema and MediaType.
|
||||
|
|
|
|||
|
|
@ -103,8 +103,8 @@ END;
|
|||
$this->assertOpenApiLogEntryContains('@OA\Parameter(name=123,in="dunno")->name is a "integer", expecting a "string" in ');
|
||||
$this->assertOpenApiLogEntryContains('@OA\Parameter(name=123,in="dunno")->in "dunno" is invalid, expecting "query", "header", "path", "cookie" in ');
|
||||
$this->assertOpenApiLogEntryContains('@OA\Parameter(name=123,in="dunno")->required is a "string", expecting a "boolean" in ');
|
||||
// $this->assertOpenApiLogEntryStartsWith('@OA\Parameter(name=123,in="dunno")->maximum is a "string", expecting a "number" in ');
|
||||
// $this->assertOpenApiLogEntryStartsWith('@OA\Parameter(name=123,in="dunno")->type must be "string", "number", "integer", "boolean", "array", "file" when @OA\Parameter()->in != "body" in ');
|
||||
// $this->assertOpenApiLogEntryStartsWith('@OA\Parameter(name=123,in="dunno")->maximum is a "string", expecting a "number" in ');
|
||||
// $this->assertOpenApiLogEntryStartsWith('@OA\Parameter(name=123,in="dunno")->type must be "string", "number", "integer", "boolean", "array", "file" when @OA\Parameter()->in != "body" in ');
|
||||
$parameter->validate();
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -74,6 +74,7 @@ class RefGenerator extends DocGenerator
|
|||
echo '<dl>' . PHP_EOL;
|
||||
foreach ($parameters as $rp) {
|
||||
$parameter = $rp->getName();
|
||||
$propertyDocumentation = $this->getPropertyDocumentation($fqdn, $parameter);
|
||||
$def = array_key_exists($parameter, $params)
|
||||
? $params[$parameter]['type']
|
||||
: '';
|
||||
|
|
@ -84,7 +85,7 @@ class RefGenerator extends DocGenerator
|
|||
|
||||
echo ' <dt><strong>' . $parameter . '</strong>' . $var . '</dt>' . PHP_EOL;
|
||||
echo ' <dd>';
|
||||
echo '<p>' . self::NO_DETAILS_AVAILABLE . '</p>';
|
||||
$this->propertyDetails($propertyDocumentation);
|
||||
echo '</dd>' . PHP_EOL;
|
||||
}
|
||||
echo '</dl>' . PHP_EOL;
|
||||
|
|
@ -131,26 +132,14 @@ class RefGenerator extends DocGenerator
|
|||
echo '<dl>' . PHP_EOL;
|
||||
foreach ($properties as $property) {
|
||||
$rp = new \ReflectionProperty($fqdn, $property);
|
||||
$propertyDocumentation = $this->extractDocumentation($rp->getDocComment());
|
||||
$propertyDocumentation = $this->getPropertyDocumentation($fqdn, $property);
|
||||
if ($var = $this->getReflectionType($fqdn, $rp, false, $propertyDocumentation['var'])) {
|
||||
$var = ' : <span style="font-family: monospace;">' . $var . '</span>';
|
||||
}
|
||||
|
||||
echo ' <dt><strong>' . $property . '</strong>' . $var . '</dt>' . PHP_EOL;
|
||||
echo ' <dd>';
|
||||
echo '<p>' . nl2br($propertyDocumentation['content'] ?: self::NO_DETAILS_AVAILABLE) . '</p>';
|
||||
if ($propertyDocumentation['see']) {
|
||||
$links = [];
|
||||
foreach ($propertyDocumentation['see'] as $see) {
|
||||
if ($link = $this->linkFromMarkup($see)) {
|
||||
$links[] = $link;
|
||||
}
|
||||
}
|
||||
if ($links) {
|
||||
echo '<p><i>See</i>: ' . implode(', ', $links) . '</p>';
|
||||
}
|
||||
}
|
||||
|
||||
$this->propertyDetails($propertyDocumentation);
|
||||
echo '</dd>' . PHP_EOL;
|
||||
}
|
||||
echo '</dl>' . PHP_EOL;
|
||||
|
|
@ -170,6 +159,36 @@ class RefGenerator extends DocGenerator
|
|||
return ob_get_clean();
|
||||
}
|
||||
|
||||
// ------------------------------------------------------------------------
|
||||
|
||||
protected function getPropertyDocumentation(string $fqdn, string $name): array
|
||||
{
|
||||
try {
|
||||
$rp = new \ReflectionProperty(str_replace('Attributes', 'Annotations', $fqdn), $name);
|
||||
} catch (\ReflectionException $re) {
|
||||
$rp = null;
|
||||
}
|
||||
|
||||
return $this->extractDocumentation($rp ? $rp->getDocComment() : null);
|
||||
}
|
||||
|
||||
protected function propertyDetails(array $propertyDocumentation): void
|
||||
{
|
||||
echo '<p>' . nl2br($propertyDocumentation['content'] ?: self::NO_DETAILS_AVAILABLE) . '</p>';
|
||||
if ($propertyDocumentation['see']) {
|
||||
$links = [];
|
||||
foreach ($propertyDocumentation['see'] as $see) {
|
||||
if ($link = $this->linkFromMarkup($see)) {
|
||||
$links[] = $link;
|
||||
}
|
||||
}
|
||||
if ($links) {
|
||||
echo '<p><i>See</i>: ' . implode(', ', $links) . '</p>';
|
||||
}
|
||||
}
|
||||
|
||||
}
|
||||
|
||||
/**
|
||||
* @param class-string<AbstractAnnotation> $fqdn
|
||||
*/
|
||||
|
|
|
|||
Loading…
Reference in New Issue