Merge pull request #22 from Lomkit/feature/documentation

🚧 automatic documentation

Author: GautierDele

.github/ISSUE_TEMPLATE/Question__or_Enhancement proposal.yml renamed to .github/ISSUE_TEMPLATE/Question_or_enhancement_proposal.yml

@@ -97,11 +97,11 @@ TODO
 ## Roadmap for the end of bêta (Estimated delivery October 2023)
 
 - Automatic documentation with extension possible
-- Refactor actions listing to --> Get resource informations (fields exposed / actions / etc ? regroupe all those possibilities)
-- Alias for includes / aggregates
+- Add tests for all commands !!!!
 
 ## Roadmap
 
 - Metrics support
 - Refactor the response class
 - Plain text search using Laravel Scout
+- Alias for includes / aggregates

README.md

@@ -27,16 +27,96 @@
     ],
 
     /*
-|--------------------------------------------------------------------------
-| Rest Authorizations
-|--------------------------------------------------------------------------
-|
-| This is the feature that automatically binds to policies to validate incoming requests.
-| Laravel Rest Api will validate each models searched / mutated / deleted to avoid leaks in your API.
-|
-*/
+    |--------------------------------------------------------------------------
+    | Rest Authorizations
+    |--------------------------------------------------------------------------
+    |
+    | This is the feature that automatically binds to policies to validate incoming requests.
+    | Laravel Rest Api will validate each models searched / mutated / deleted to avoid leaks in your API.
+    |
+    */
 
     'authorizations' => [
         'enabled' => true
     ],
+
+    /*
+    |--------------------------------------------------------------------------
+    | Rest Documentation
+    |--------------------------------------------------------------------------
+    |
+    | This is the feature that generates automatically your API documentation for you.
+    | Laravel Rest Api will validate each models searched / mutated / deleted to avoid leaks in your API.
+    | This feature is based on OpenApi, for more detail see: https://swagger.io/specification/
+    |
+    */
+
+    'documentation' => [
+        'routing' => [
+            'enabled' => true,
+            'domain' => null,
+            'path' => '/api-documentation',
+            'middlewares' => [
+                'web'
+            ]
+        ],
+        'info' => [
+            'title' => config('app.name'),
+            'summary' => 'This is my projet\'s documentation',
+            'description' => 'Find out all about my projet\'s API',
+            'termsOfService' => null, // (Optional) Url to terms of services
+            'contact' => [
+                'name' => 'My Company',
+                'email' => 'email@company.com',
+                'url' => 'https://company.com'
+            ],
+            'license' => [
+                'url' => null,
+                'name' => 'Apache 2.0',
+                'identifier' => 'Apache-2.0'
+            ],
+            'version' => '1.0.0'
+        ],
+        // See https://spec.openapis.org/oas/v3.1.0#server-object
+        'servers' => [
+            [
+                'url' => '/', // Relative to current
+                'description' => 'The current server'
+            ],
+//            [
+//                'url' => '"https://my-server.com:{port}/{basePath}"',
+//                'description' => 'Production server',
+//                'variables' => [
+//                    'port' => [
+//                        'enum' => ['80', '443'],
+//                        'default' => '443'
+//                    ],
+//                    'basePath' => [
+//                        'default' => 'v2',
+//                        'enum' => ['v1', 'v2'],
+//                    ]
+//                ]
+//            ]
+        ],
+        // See https://spec.openapis.org/oas/v3.1.0#security-scheme-object
+        'security' => [
+//            [
+//                'type' => 'http',
+//                'description' => 'description',
+//                'scheme' => 'Bearer',
+//                'bearerFormat' => 'JWT'
+//            ],
+//            [
+//                'type' => 'oauth2',
+//                'flows' => [
+//                    'authorizationCode' => [
+//                        'scopes' => ['write:pets'],
+//                        'tokenUrl' => 'https://example.com/api/oauth/token',
+//                        'authorizationUrl' => 'https://example.com/api/oauth/dialog',
+//                        'refreshUrl' => 'https://example.com/api/oauth/refresh',
+//                    ]
+//                ]
+//            ]
+        ]
+    ],
 ];

config/rest.php

@@ -0,0 +1,25 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta
+            name="description"
+            content="SwaggerUI"
+    />
+    <title>SwaggerUI</title>
+    <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5.4.2/swagger-ui.css" />
+</head>
+<body>
+<div id="swagger-ui"></div>
+<script src="https://unpkg.com/swagger-ui-dist@5.4.2/swagger-ui-bundle.js" crossorigin></script>
+<script>
+    window.onload = () => {
+        window.ui = SwaggerUIBundle({
+            url: '/vendor/rest/openapi.json',
+            dom_id: '#swagger-ui',
+        });
+    };
+</script>
+</body>
+</html>

resources/views/index.blade.php

@@ -0,0 +1,65 @@
+<?php
+
+namespace Lomkit\Rest\Console\Commands;
+
+use Illuminate\Console\Command;
+use Illuminate\Console\GeneratorCommand;
+use Illuminate\Contracts\Console\PromptsForMissingInput;
+use Illuminate\Database\Migrations\MigrationCreator;
+use Illuminate\Support\Composer;
+use Illuminate\Support\Str;
+use Lomkit\Rest\Console\ResolvesStubPath;
+use Lomkit\Rest\Documentation\Schemas\Contact;
+use Lomkit\Rest\Documentation\Schemas\Info;
+use Lomkit\Rest\Documentation\Schemas\License;
+use Lomkit\Rest\Documentation\Schemas\OpenAPI;
+use RuntimeException;
+
+class DocumentationCommand extends GeneratorCommand implements PromptsForMissingInput
+{
+    /**
+     * The console command signature.
+     *
+     * @var string
+     */
+    protected $signature = 'rest:documentation
+        {--path= : The location where the documentation file should be created}';
+
+    /**
+     * The console command description.
+     *
+     * @var string
+     */
+    protected $description = 'Generate the documentation';
+
+    public function handle()
+    {
+        $openApi = (new OpenAPI)
+            ->generate();
+
+        $path = $this->getPath('openapi');
+
+        $this->makeDirectory($path);
+
+        $this->files->put(
+            $path,
+            json_encode($openApi->jsonSerialize())
+        );
+    }
+
+    /**
+     * Get the documentation path.
+     *
+     * @param  string  $name
+     * @return string
+     */
+    protected function getPath($name)
+    {
+        return public_path('vendor/rest/'.$name.'.json');
+    }
+
+    protected function getStub()
+    {
+        throw new RuntimeException('Should not be here');
+    }
+}

src/Console/Commands/DocumentationCommand.php

@@ -0,0 +1,74 @@
+<?php
+
+namespace Lomkit\Rest\Documentation\Schemas;
+
+class Contact extends Schema
+{
+    /**
+     * The identifying name of the contact person/organization.
+     * @var string
+     */
+    protected string $name;
+
+    /**
+     * The URL pointing to the contact information.
+     * @var string
+     */
+    protected string $url;
+
+    /**
+     * The email address of the contact person/organization.
+     * @var string
+     */
+    protected string $email;
+
+    public function withName(string $name): Contact
+    {
+        $this->name = $name;
+        return $this;
+    }
+
+    public function name(): string
+    {
+        return $this->name;
+    }
+
+    public function withUrl(string $url): Contact
+    {
+        $this->url = $url;
+        return $this;
+    }
+
+    public function url(): string
+    {
+        return $this->url;
+    }
+
+    public function withEmail(string $email): Contact
+    {
+        $this->email = $email;
+        return $this;
+    }
+
+    public function email(): string
+    {
+        return $this->email;
+    }
+
+    public function jsonSerialize(): mixed
+    {
+        return [
+            'name' => $this->name(),
+            'url' => $this->url(),
+            'email' => $this->email()
+        ];
+    }
+
+    public function generate(): Contact
+    {
+        return $this
+            ->withName(config('rest.documentation.info.contact.name'))
+            ->withEmail(config('rest.documentation.info.contact.email'))
+            ->withUrl(config('rest.documentation.info.contact.url'));
+    }
+}

src/Documentation/Schemas/Contact.php

@@ -0,0 +1,35 @@
+<?php
+
+namespace Lomkit\Rest\Documentation\Schemas;
+
+use Lomkit\Rest\Http\Controllers\Controller;
+
+class Example extends Schema
+{
+    /**
+     * Value
+     * @var string
+     */
+    protected array $value;
+
+    public function jsonSerialize(): mixed
+    {
+        return $this->value();
+    }
+
+    public function generate(): Example
+    {
+        return $this;
+    }
+
+    public function withValue(array $value): Example
+    {
+        $this->value = $value;
+        return $this;
+    }
+
+    public function value(): array
+    {
+        return $this->value;
+    }
+}

src/Documentation/Schemas/Example.php

@@ -0,0 +1,51 @@
+<?php
+
+namespace Lomkit\Rest\Documentation\Schemas;
+
+use Lomkit\Rest\Http\Controllers\Controller;
+
+class Examples extends Schema
+{
+    /**
+     * Examples
+     * @var array
+     */
+    protected array $examples = [];
+
+    public function withExamples(array $examples): Examples
+    {
+        $this->examples = array_merge($this->examples, $examples);
+        return $this;
+    }
+
+    public function examples(): array
+    {
+        return $this->examples;
+    }
+
+    public function jsonSerialize(): mixed
+    {
+        return collect($this->examples())->map->jsonSerialize()->toArray();
+    }
+
+    public function generate(): Examples
+    {
+        return $this;
+    }
+
+    public function generateDetail(Controller $controller): Examples
+    {
+        return $this
+            ->withExamples(
+                [
+                    'application/json' => (new Example)
+                        ->withExample(
+                            json_encode(
+                                ['test1234' => 'OAZEOOEZAOEOAZ']
+                            )
+                        )
+                ]
+            )
+            ->generate();
+    }
+}

src/Documentation/Schemas/Examples.php

@@ -0,0 +1,11 @@
+<?php
+
+namespace Lomkit\Rest\Documentation\Schemas;
+
+class Header extends Parameter
+{
+    public function withName(string $name): Parameter
+    {
+        throw new \RuntimeException('Name is forbidden on headers');
+    }
+}