Add custom responses capability

Author: Mezatsong

LICENSE.md

@@ -0,0 +1,19 @@
+# The MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

README.md

@@ -7,11 +7,12 @@ Also includes Swagger UI.
 This package is heavily inspired by the [darki73/laravel-swagger](https://github.com/darki73/laravel-swagger) and [kevupton/laravel-swagger](https://github.com/kevupton/laravel-swagger).  
 Usage is pretty similar to the [mtrajano/laravel-swagger](https://github.com/mtrajano/laravel-swagger) with the difference being:
 1. OAS3 support
-2. "Custom decorators" inspired by Nest.JS
-3. Automatic generation (assuming relevant configuration option is turned on)
-4. Inclusion of Swagger UI
-5. Models generations
-6. Generate operation tags based on route prefix or controller's name
+2. Custom decorators
+3. Custom responses
+4. Automatic generation (assuming relevant configuration option is turned on)
+5. Inclusion of Swagger UI
+6. Models generations
+7. Generate operation tags based on route prefix or controller's name
 
 
 ## Installation
@@ -64,29 +65,58 @@ public function someMethod(Request $request) {}
 
 ### @Response() decorator
 You can have multiple `@Response` decorators
+- The `code` property is required and must be the first in propery
+- You can use the optional `description` property to desscribe your response
+- You can use the optional `ref` property to refer a model, you can also wrap that model in [] to refer an array of that model or use the full model path inside, finally you can use a schema builder
 ```php
 /**
 * @Response({
 *     code: 200
-*     description: get user
+*     description: return user model
 *     ref: User
 * })
 * @Response({
-*     code: 302
-*     description: Redirect
+*     code: 400
+*     description: Bad Request, array of APIError model
+*     ref: [APIError]
 * })
 * @Response({
-*     code: 400
-*     description: Bad Request
+*     code: 302
+*     description: Redirect
 * })
 * @Response({
 *     code: 500
 *     description: Internal Server Error
 * })
 */
 public function someMethod(Request $request) {}
+
+/**
+ * You can also refer object directly
+ * 
+ * 
+ * @Response({
+ *     code: 200
+ *     description: direct user model reference
+ *     ref: #/components/schemas/User
+ * })
+ */
+public function someMethod2(Request $request) {}
+
+/**
+ * Using P schema builder for Laravel Pagination
+ * 
+ * @Response({
+ *     code: 200
+ *     description: a laravel pagination instance with User model
+ *     ref: P(User)
+ * })
+ */
+public function someMethod3(Request $request) {}
 ```
 
+##### Note: You can see all available schema builder or create your own schema builder, explore swagger.schema_builders config for more informations.
+
 ### Custom Validators
 These validators are made purely for visual purposes, however, some of them can actually do validation
 

config/swagger.php

@@ -2,6 +2,13 @@
 
 return [
 
+    /**
+     * Weather swagger is enabled
+     * if you set false, this will
+     * only hide swagger's route
+     */
+    'enable'                    => env('SWAGGER_ENABLE', false),
+
     /**
      * API Title
      */
@@ -143,4 +150,15 @@
         'bearerAuth'            =>  'http',
     ],
 
+    /**
+     * Schema builder for custom swagger responses.
+     *
+     * You can implement your own schema builder, see example in this existing implementation
+     * Note that Schema builder must implement Mezatsong\SwaggerDocs\Responses\SchemaBuilder
+     */
+    'schema_builders'            => [
+        'P' => \Mezatsong\SwaggerDocs\Responses\SchemaBuilders\LaravelPaginateSchemaBuilder::class,
+        'SP' => \Mezatsong\SwaggerDocs\Responses\SchemaBuilders\LaravelSimplePaginateSchemaBuilder::class,
+    ]
+
 ];

src/Definitions/DefinitionGenerator.php

@@ -4,9 +4,11 @@
 use Illuminate\Support\Collection;
 use Illuminate\Container\Container;
 use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Str;
 use Illuminate\Support\Facades\File;
 use Illuminate\Support\Facades\Schema;
 use Illuminate\Database\Eloquent\Model;
+use Illuminate\Support\Arr;
 use phpDocumentor\Reflection\DocBlockFactory;
 
 /**
@@ -107,6 +109,8 @@ function generateSchemas(): array {
                         $data['default'] = $default;
                     }
 
+                    $this->addExampleKey($data);
+
                     $properties[$item] = $data;
 
                     if ($column->getNotnull()) {
@@ -115,8 +119,9 @@ function generateSchemas(): array {
                 }
 
                 foreach ($with->getValue($obj) as $item) {
-                    $class        = get_class($obj->{$item}()->getModel());
+                    $class = get_class($obj->{$item}()->getModel());
                     $properties[$item] = [
+                        'type' => 'object',
                         '$ref' => '#/components/schemas/' . last(explode('\\', $class)),
                     ];
                 }
@@ -147,4 +152,57 @@ function getModels(): array {
     private function getModelName($model): string {
         return last(explode('\\', get_class($model)));
     }
+
+
+    private function addExampleKey(array & $property): void {
+        if (Arr::has($property, 'type')) {
+            switch ($property['type']) {
+                case 'bigserial':
+                case 'bigint':
+                    Arr::set($property, 'example', rand(1000000000000000000, 9200000000000000000));
+                    break;
+                case 'serial':
+                case 'integer':
+                    Arr::set($property, 'example', rand(1000000000, 2000000000));
+                    break;
+                case 'mediumint':
+                    Arr::set($property, 'example', rand(1000000, 8000000));
+                    break;
+                case 'smallint':
+                    Arr::set($property, 'example', rand(10000, 32767));
+                    break;
+                case 'tinyint':
+                    Arr::set($property, 'example', rand(100, 127));
+                    break;
+                case 'decimal':
+                case 'float':
+                case 'double':
+                case 'real':
+                    Arr::set($property, 'example', 0.5);
+                    break;
+                case 'date':
+                    Arr::set($property, 'example', date('Y-m-d'));
+                    break;
+                case 'time':
+                    Arr::set($property, 'example', date('H:i:s'));
+                    break;
+                case 'datetime':
+                    Arr::set($property, 'example', date('Y-m-d H:i:s'));
+                    break;
+                case 'string':
+                    Arr::set($property, 'example', 'string');
+                    break;
+                case 'text':
+                    Arr::set($property, 'example', 'a long text');
+                    break;
+                case 'boolean':
+                    Arr::set($property, 'example', rand(0,1) == 0);
+                    break;
+
+                default:
+                    # code...
+                    break;
+            }
+        }
+    }
 }

src/Exceptions/SchemaBuilderNotFound.php

@@ -0,0 +1,9 @@
+<?php namespace Mezatsong\SwaggerDocs\Exceptions;
+
+use Exception;
+
+/**
+ * Class SchemaBuilderNotFound
+ * @package Mezatsong\SwaggerDocs\Exceptions
+ */
+class SchemaBuilderNotFound extends Exception {}

src/Generator.php

@@ -2,6 +2,7 @@
 
 use Exception;
 use Mezatsong\SwaggerDocs\Exceptions\InvalidDefinitionException;
+use ReflectionClass;
 use ReflectionMethod;
 use ReflectionException;
 use Illuminate\Support\Arr;
@@ -19,6 +20,7 @@
 use Laravel\Passport\Http\Middleware\CheckForAnyScope;
 use Mezatsong\SwaggerDocs\Definitions\DefinitionGenerator;
 use Mezatsong\SwaggerDocs\Exceptions\InvalidAuthenticationFlow;
+use Mezatsong\SwaggerDocs\Exceptions\SchemaBuilderNotFound;
 
 /**
  * Class Generator
@@ -256,11 +258,11 @@ private function generatePath(DataObjects\Route $route, string $method, ?string
         $actionMethodInstance = $this->getActionMethodInstance($route);
         $documentationBlock = $actionMethodInstance ? ($actionMethodInstance->getDocComment() ?: ''): '';
 
-        $documentation = $this->parseActionDocumentationBlock($documentationBlock);
+        $documentation = $this->parseActionDocumentationBlock($documentationBlock, $route->uri());
 
         $this->addActionsParameters($documentation, $route, $method, $actionMethodInstance);
 
-        $this->addActionsResponses($documentation, $route, $method, $actionMethodInstance);
+        $this->addActionsResponses($documentation);
 
         if ($this->hasSecurityDefinitions) {
             $this->addActionScopes($documentation, $route);
@@ -318,13 +320,14 @@ private function getActionMethodInstance(DataObjects\Route $route): ?ReflectionM
      * @param string $documentationBlock
      * @return array
      */
-    private function parseActionDocumentationBlock(string $documentationBlock): array {
+    private function parseActionDocumentationBlock(string $documentationBlock, string $uri): array {
         $documentation = [
             'summary'       =>  '',
             'description'   =>  '',
             'deprecated'    =>  false,
             'responses'     =>  [],
         ];
+
         if (empty($documentationBlock) || !$this->fromConfig('parse.docBlock', false)) {
             return $documentation;
         }
@@ -365,25 +368,89 @@ private function parseActionDocumentationBlock(string $documentationBlock): arra
                         } else if ($key === 'description') {
                             $documentation['responses'][$responseCode]['description'] = $value;
                         } else if ($key === 'ref') {
-                            $ref = $value;
-                            if (!Str::startsWith($value, '#/components/schemas/')) {
-                                foreach ($this->definitionGenerator->getModels() as $item) {
-                                    if (Str::contains($item, $value)) {
-                                        $ref = "#/components/schemas/$value";
-                                    }
+
+                            $value = str_replace(' ', '', $value);
+                            $matches = [];
+
+                            if (Str::startsWith($value, '[') && Str::endsWith($value, ']')) {
+                                $modelName = trim(Str::replaceFirst('[', '' , Str::replaceLast(']', '' , $value)));
+                                $ref = $this->toSwaggerModelPath($modelName);
+                                $items = [
+                                    'type' => 'array',
+                                    'items' => [
+                                        'type' => 'object',
+                                        '$ref' => $ref
+                                    ]
+                                ];
+                                $documentation['responses'][$responseCode]['content']['application/json']['schema'] = $items;
+                            } else if (preg_match("(([A-Za-z]{1,})\(([A-Za-z]{1,})\))", $value, $matches) === 1) {
+                                $schema = $this->generateCustomResponseSchema(
+                                    $matches[1],
+                                    $matches[2],
+                                    $uri
+                                );
+                                if (\count($schema) > 0) {
+                                    $documentation['responses'][$responseCode]['content']['application/json']['schema'] = $schema;
                                 }
+                            } else {
+                                $ref = $this->toSwaggerModelPath($value);
+                                $documentation['responses'][$responseCode]['content']['application/json']['schema']['$ref'] = $ref;
                             }
-                            $documentation['responses'][$responseCode]['content']['application/json']['schema']['$ref'] = $ref;
+
                         }
                     }
                 }
             }
 
-
-            return $documentation;
         } catch (Exception $exception) {
-            return $documentation;
+            if ($exception instanceof SchemaBuilderNotFound) {
+                throw $exception;
+            }
+        }
+
+        return $documentation;
+    }
+
+
+    /**
+     * Read schemas builder config and call the matched one
+     *
+     * @throws SchemaBuilderNotFound
+     */
+    private function generateCustomResponseSchema(string $operation, string $model, string $uri) {
+        $ref = $this->toSwaggerModelPath($model);
+        $schemaBuilders = $this->fromConfig('schema_builders');
+
+        if (!Arr::has($schemaBuilders, $operation)) {
+            throw new SchemaBuilderNotFound("schema builder $operation not found in swagger.schema_builders config");
         }
+
+        $actionClass = new ReflectionClass($schemaBuilders[$operation]);
+
+        try {
+            return $actionClass->newInstanceWithoutConstructor()->build($ref, $uri);
+        } catch(Exception $e) {
+            throw new Exception("SchemaBuilder must implements Mezatsong\SwaggerDocs\Responses\SchemaBuilder interface");
+        }
+    }
+
+
+    /**
+     * Turn a model name to swagger path to that model or
+     * return the same string if it's already a valide path
+     * @param string $value
+     * @return string
+     */
+    private function toSwaggerModelPath(string $value): string {
+        if (!Str::startsWith($value, '#/components/schemas/')) {
+            foreach ($this->definitionGenerator->getModels() as $item) {
+                if (Str::endsWith($item, $value)) {
+                    return "#/components/schemas/$value";
+                }
+            }
+        }
+
+        return $value;
     }
 
 
@@ -394,9 +461,7 @@ private function parseActionDocumentationBlock(string $documentationBlock): arra
      * @param string $method
      * @param ReflectionMethod|null $actionInstance
      */
-    private function addActionsResponses(array & $information, DataObjects\Route $route, string $method, ?ReflectionMethod $actionInstance): void {
-
-
+    private function addActionsResponses(array & $information): void {
 
         if (\count(Arr::get($information, 'responses')) === 0) {
             Arr::set($information, 'responses', [

src/Parameters/BodyParametersGenerator.php

@@ -130,7 +130,7 @@ protected function getNestedParameterType(array $nameTokens): string {
      */
     protected function createNewPropertyObject(string $type, array $rules): array {
         $propertyObject = [
-            'type'      =>  $type,
+            'type' =>  $type,
         ];
 
         if ($enums = $this->getEnumValues($rules)) {