Skip to content

Commit

Permalink
Merge branch 'swagger/openApi-3.0'
Browse files Browse the repository at this point in the history
  • Loading branch information
DarkaOnLine committed Feb 19, 2018
2 parents 0f9e6e7 + 99ec1c8 commit ee1de13
Show file tree
Hide file tree
Showing 9 changed files with 157 additions and 21 deletions.
12 changes: 9 additions & 3 deletions .travis.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
22 changes: 20 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand All @@ -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`.
Expand Down
2 changes: 1 addition & 1 deletion composer.json
Original file line number Diff line number Diff line change
Expand Up @@ -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": {
Expand Down
4 changes: 0 additions & 4 deletions config/l5-swagger.php
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
<?php

return [

'api' => [
/*
|--------------------------------------------------------------------------
Expand All @@ -13,7 +12,6 @@
],

'routes' => [

/*
|--------------------------------------------------------------------------
| Route for accessing api documentation interface
Expand Down Expand Up @@ -49,11 +47,9 @@
'docs' => [],
'oauth2_callback' => [],
],

],

'paths' => [

/*
|--------------------------------------------------------------------------
| Absolute path to location where parsed swagger annotations will be stored
Expand Down
2 changes: 1 addition & 1 deletion tests/ConsoleTest.php
Original file line number Diff line number Diff line change
Expand Up @@ -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 */
Expand Down
8 changes: 6 additions & 2 deletions tests/GeneratorTest.php
Original file line number Diff line number Diff line change
Expand Up @@ -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');
Expand All @@ -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();
}
Expand Down
26 changes: 18 additions & 8 deletions tests/TestCase.php
Original file line number Diff line number Diff line change
Expand Up @@ -7,13 +7,6 @@

class TestCase extends OrchestraTestCase
{
protected function getPackageProviders($app)
{
return [
L5SwaggerServiceProvider::class,
];
}

public function setUp()
{
parent::setUp();
Expand All @@ -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(), '{}');
Expand All @@ -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
Expand Down
102 changes: 102 additions & 0 deletions tests/storage/annotations/OpenApi/Anotations.php
Original file line number Diff line number Diff line change
@@ -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"}
* }
* },
* )
*/

0 comments on commit ee1de13

Please sign in to comment.