add support of examples

Author: František Mazura

README.md

@@ -165,4 +165,8 @@ Check `examples/cartore/CarController.php` controller and `exmples/carstore/Open
 
 # TODO
 
-Update `composer.json` after [pull request](https://github.com/vyuldashev/laravel-openapi/pull/37) is accepted.
+Update `composer.json` after [pull request](https://github.com/vyuldashev/laravel-openapi/pull/37) is accepted.
+
+# Changes
+
+- 2021-03-05 - support `@example`

examples/carstore/OpenApi/RequestBodies/CarValueObject.php

@@ -9,6 +9,9 @@ class CarValueObject
 	 *
 	 * This is a car name description...
 	 *
+	 * @example My best car
+	 * @example Skoda Octavia
+	 * @example M1A1
 	 * @var string
 	 */
 	protected string $name;

src/DocParseHelper.php

@@ -58,6 +58,27 @@ public static function getComments(string $phpDoc)
 		return $out;
 	}
 
+	public static function getExamples(string $phpDoc)
+	{
+		$out = null;
+		$lines = explode("\n", $phpDoc);
+		foreach ($lines as $line) {
+			$line = trim($line);
+			$line = str_replace("/**", '', $line);
+			$line = str_replace("*/", '', $line);
+			$line = str_replace("*", '', $line);
+			$line = ltrim($line);
+			preg_match("/@example (.*)/", $line, $matches);
+			$example = $matches[1] ?? null;
+			if (!empty($example)) {
+				if (empty($out)) {
+					$out = [];
+				}
+				$out[] = $example;
+			}
+		}
+		return $out;
+	}
 
 	public static function getAllParams(string $phpDoc)
 	{
@@ -83,12 +104,16 @@ public static function getAllParams(string $phpDoc)
 	public static function addCommentsToSchema(string $phpDoc, Schema $schema): Schema
 	{
 		$comments = self::getComments($phpDoc);
+		$examples = self::getExamples($phpDoc);
 
 		if (!empty($comments) && sizeof($comments) > 0) {
 			$schema = $schema->title($comments[0]);
 			if ((sizeof($comments) > 1)) {
 				$schema = $schema->description(implode("\n", array_slice($comments, 1)));
 			}
+			if (!empty($examples)) {
+				$schema = $schema->example(implode(', ', $examples));
+			}
 		}
 
 		return $schema;

tests/CarstoreTest.php

@@ -28,6 +28,7 @@ public function testGenerate(): void
 						[
 							'title' => 'Car name',
 							'description' => 'This is a car name description...',
+							'example' => 'My best car, Skoda Octavia, M1A1',
 							'type' => 'string',
 							'nullable' => false,
 						],