Merge branch 'swagger/openApi-3.0'

.travis.yml

@@ -6,19 +6,25 @@ env:
   global:
   - DEFAULT_COMPOSER_FLAGS="--no-interaction --no-progress --optimize-autoloader"
   - REPORT_TESTS_COVERAGE=0
+  - SWAGGER_VERSION=2.0
 matrix:
   fast_finish: true
   include:
   - php: 7.1
+    env: CACHE_NAME=SWAGGER
+  - php: 7.1
+    env: SWAGGER_VERSION=3.0 CACHE_NAME=OPEN_API
+  - php: 7.2
+    env: REPORT_TESTS_COVERAGE=1 CACHE_NAME=SWAGGER
   - php: 7.2
-    env: REPORT_TESTS_COVERAGE=1
+    env: SWAGGER_VERSION=3.0 CACHE_NAME=OPEN_API
 cache:
   directories:
   - "$HOME/.composer/cache"
-before_install:
-  - travis_retry composer global require $DEFAULT_COMPOSER_FLAGS hirak/prestissimo
 install:
   - travis_retry composer update $DEFAULT_COMPOSER_FLAGS
+  - if [ $SWAGGER_VERSION == 2.0 ]; then composer require 'zircote/swagger-php:2.*'; fi
+  - if [ $SWAGGER_VERSION == 3.0 ]; then composer require 'zircote/swagger-php:3.*'; fi
   - composer info -D | sort
 before_script:
   - curl -L https://codeclimate.com/downloads/test-reporter/test-reporter-latest-linux-amd64 > ./cc-test-reporter

README.md

@@ -21,8 +21,8 @@ Installation
  5.3.x    | 2.2       | 1.1, 1.2, 2.0              | ```php composer require "darkaonline/l5-swagger:~3.0" ```
  5.4.x    | 2.2       | 1.1, 1.2, 2.0              | ```php composer require "darkaonline/l5-swagger:~4.0" ```
  5.4.x    | 3         | 2.0                        | ```php composer require "darkaonline/l5-swagger:5.4.*" ```
- 5.5.x    | 3         | 2.0                        | ```php composer require "darkaonline/l5-swagger:5.5.*" ```
- 5.6.x    | 3         | 2.0                        | ```php composer require "darkaonline/l5-swagger:5.6.*" ```
+ 5.5.x    | 3         | 2.0, 3.0                        | ```php composer require "darkaonline/l5-swagger:5.5.*" ```
+ 5.6.x    | 3         | 2.0, 3.0                        | ```php composer require "darkaonline/l5-swagger:5.6.*" ```
 
 You can publish L5-Swagger's config and view files into your project by running:
 
@@ -41,6 +41,24 @@ or open your `config/app.php` and add this line in `providers` section
 L5Swagger\L5SwaggerServiceProvider::class,
 ```
 
+Using [OpenApi 3.0 Specification](https://github.com/OAI/OpenAPI-Specification)
+============
+If you would like to use lattes OpenApi specifications (originally known as the Swagger Specification) in you project you should:
+- Explicitly require `swagger-php` version 3.* in your projects composer by running:
+```bash
+composer require 'zircote/swagger-php:3.*'
+```
+- Set environment variable `SWAGGER_VERSION` to **3.0** in your `.env` file:
+```
+SWAGGER_VERSION=3.0
+```
+or in your `config/l5-swagger.php`:
+```php
+'swagger_version' => env('SWAGGER_VERSION', '3.0'),
+```
+- Use examples provided here: https://github.com/zircote/swagger-php/tree/3.x/Examples/petstore-3.0
+
+
 Using Swagger UI with Passport
 ============
 The easiest way to build and test your Laravel-based API using Swagger-php is to use Passport's `CreateFreshApiToken` middleware. This middleware, built into Laravel's core, adds a cookie to all responses, and the cookie authenticates all subsequent requests through Passport's `TokenGuard`.

composer.json

@@ -16,7 +16,7 @@
   "require": {
     "php": ">=7.1.3",
     "laravel/framework": "5.6.*",
-    "zircote/swagger-php": "~2.0",
+    "zircote/swagger-php": "~2.0|3.*",
     "swagger-api/swagger-ui": "^3.0"
   },
   "require-dev": {

config/l5-swagger.php

@@ -1,7 +1,6 @@
 <?php
 
 return [
-
     'api' => [
         /*
         |--------------------------------------------------------------------------
@@ -13,7 +12,6 @@
     ],
 
     'routes' => [
-
         /*
         |--------------------------------------------------------------------------
         | Route for accessing api documentation interface
@@ -49,11 +47,9 @@
             'docs' => [],
             'oauth2_callback' => [],
         ],
-
     ],
 
     'paths' => [
-
         /*
         |--------------------------------------------------------------------------
         | Absolute path to location where parsed swagger annotations will be stored

tests/ConsoleTest.php

@@ -18,7 +18,7 @@ public function canGenerate()
         $fileContent = file_get_contents($this->jsonDocsFile());
 
         $this->assertJson($fileContent);
-        $this->assertContains('L5 Swagger API', $fileContent);
+        $this->assertContains('L5 Swagger', $fileContent);
     }
 
     /** @test */

tests/GeneratorTest.php

@@ -16,14 +16,18 @@ public function canGenerateApiJsonFile()
         $this->assertTrue(file_exists($this->jsonDocsFile()));
 
         $this->get(route('l5-swagger.docs'))
-            ->assertSee('L5 Swagger API')
+            ->assertSee('L5 Swagger')
             ->assertSee('my-default-host.com')
             ->isOk();
     }
 
     /** @test */
     public function canGenerateApiJsonFileWithChangedBasePath()
     {
+        if ($this->isOpenApi() == true) {
+            $this->markTestSkipped('only for openApi 2.0');
+        }
+
         $this->setAnnotationsPath();
 
         $cfg = config('l5-swagger');
@@ -35,7 +39,7 @@ public function canGenerateApiJsonFileWithChangedBasePath()
         $this->assertTrue(file_exists($this->jsonDocsFile()));
 
         $this->get(route('l5-swagger.docs'))
-            ->assertSee('L5 Swagger API')
+            ->assertSee('L5 Swagger')
             ->assertSee('new_path')
             ->isOk();
     }

tests/TestCase.php

@@ -7,13 +7,6 @@
 
 class TestCase extends OrchestraTestCase
 {
-    protected function getPackageProviders($app)
-    {
-        return [
-            L5SwaggerServiceProvider::class,
-        ];
-    }
-
     public function setUp()
     {
         parent::setUp();
@@ -30,6 +23,18 @@ public function tearDown()
         parent::tearDown();
     }
 
+    protected function isOpenApi()
+    {
+        return version_compare(config('l5-swagger.swagger_version'), '3.0', '>=');
+    }
+
+    protected function getPackageProviders($app)
+    {
+        return [
+            L5SwaggerServiceProvider::class,
+        ];
+    }
+
     protected function crateJsonDocumentationFile()
     {
         file_put_contents($this->jsonDocsFile(), '{}');
@@ -47,7 +52,12 @@ protected function jsonDocsFile()
     protected function setAnnotationsPath()
     {
         $cfg = config('l5-swagger');
-        $cfg['paths']['annotations'] = __DIR__.'/storage/annotations';
+        $cfg['paths']['annotations'] = __DIR__.'/storage/annotations/Swagger';
+
+        if ($this->isOpenApi()) {
+            $cfg['paths']['annotations'] = __DIR__.'/storage/annotations/OpenApi';
+        }
+
         $cfg['generate_always'] = true;
 
         //Adding constants which will be replaced in generated json file

tests/storage/annotations/OpenApi/Anotations.php

@@ -0,0 +1,102 @@
+<?php
+
+/**
+ * @OAS\Info(
+ *      version="1.0.0",
+ *      title="L5 OpenApi",
+ *      description="L5 Swagger OpenApi description",
+ *      @OAS\Contact(
+ *          email="[email protected]"
+ *      ),
+ *     @OAS\License(
+ *         name="Apache 2.0",
+ *         url="http://www.apache.org/licenses/LICENSE-2.0.html"
+ *     )
+ * )
+ */
+
+/**
+ *  @OAS\Server(
+ *      url=L5_SWAGGER_CONST_HOST,
+ *      description="L5 Swagger OpenApi dynamic host server"
+ *  )
+ *
+ *  @OAS\Server(
+*      url="https://projects.dev/api/v1",
+ *      description="L5 Swagger OpenApi Server"
+ * )
+ */
+
+/**
+ * @OAS\Tag(
+ *     name="project",
+ *     description="Everything about your Projects",
+ *     @OAS\ExternalDocumentation(
+ *         description="Find out more",
+ *         url="http://swagger.io"
+ *     )
+ * )
+ *
+ * @OAS\Tag(
+ *     name="user",
+ *     description="Operations about user",
+ *     @OAS\ExternalDocumentation(
+ *         description="Find out more about",
+ *         url="http://swagger.io"
+ *     )
+ * )
+ * @OAS\ExternalDocumentation(
+ *     description="Find out more about Swagger",
+ *     url="http://swagger.io"
+ * )
+ */
+
+/**
+ * @OAS\Get(
+ *      path="/projects",
+ *      operationId="getProjectsList",
+ *      tags={"Projects"},
+ *      summary="Get list of projects",
+ *      description="Returns list of projects",
+ *      @OAS\Response(
+ *          response=200,
+ *          description="successful operation"
+ *       ),
+ *       @OAS\Response(response=400, description="Bad request"),
+ *       security={
+ *           {"api_key_security_example": {}}
+ *       }
+ *     )
+ *
+ * Returns list of projects
+ */
+
+/**
+ * @OAS\Get(
+ *      path="/projects/{id}",
+ *      operationId="getProjectById",
+ *      tags={"Projects"},
+ *      summary="Get project information",
+ *      description="Returns project data",
+ *      @OAS\Parameter(
+ *          name="id",
+ *          description="Project id",
+ *          required=true,
+ *          in="path",
+ *          @OAS\Schema(
+ *              type="integer"
+ *          )
+ *      ),
+ *      @OAS\Response(
+ *          response=200,
+ *          description="successful operation"
+ *       ),
+ *      @OAS\Response(response=400, description="Bad request"),
+ *      @OAS\Response(response=404, description="Resource Not Found"),
+ *      security={
+ *         {
+ *             "oauth2_security_example": {"write:projects", "read:projects"}
+ *         }
+ *     },
+ * )
+ */