From b149af0c0de894713c0e6d9fb7a134d0cd360dba Mon Sep 17 00:00:00 2001
From: Roman Lytvynenko <litvinenko95@gmail.com>
Date: Wed, 21 Sep 2022 00:07:38 +0300
Subject: [PATCH] documentation for security

---
 docs/usage/access.md              |  4 +-
 docs/usage/security.md            | 61 +++++++++++++++++++++++++++++++
 src/Support/Generator/OpenApi.php |  2 +
 tests/OpenApiBuildersTest.php     |  3 +-
 4 files changed, 66 insertions(+), 4 deletions(-)
 create mode 100644 docs/usage/security.md

diff --git a/docs/usage/access.md b/docs/usage/access.md
index 9318321e..9105c038 100644
--- a/docs/usage/access.md
+++ b/docs/usage/access.md
@@ -1,9 +1,9 @@
 ---
 title: Docs authorization
-weight: 4
+weight: 5
 ---
 
-Scramble exposes docs at the `/docs/api` URI. By default, you will only be able to access this dashboard in the `local` environment.
+Scramble exposes docs at the `/docs/api` URI. By default, you will only be able to access this route in the `local` environment.
 
 If you need to allow access to docs in `production` environment, implement gate called `viewApiDocs`:
 
diff --git a/docs/usage/security.md b/docs/usage/security.md
new file mode 100644
index 00000000..58c5f58b
--- /dev/null
+++ b/docs/usage/security.md
@@ -0,0 +1,61 @@
+---
+title: Security
+weight: 4
+---
+
+Most likely, your API is protected by some sort of the auth. OpenAPI have plenty of ways to describe the API (see full documentation of spec here https://spec.openapis.org/oas/v3.1.0#security-scheme-object).
+
+## Adding security scheme
+Scramble allows you to document how your API is secured. To document this, you can use `Scramble::extendOpenApi` method and add security information to OpenAPI document using `secure` method.
+
+You should call `extendOpenApi` in `register` method of some of your service providers. This method accepts a callback that accepts OpenAPI document as a first argument.
+
+`secure` method on `OpenApi` object accepts security scheme as an argument. It makes the security scheme default for all endpoints.
+
+```php
+namespace App\Providers;
+
+use Dedoc\Scramble\Support\Generator\OpenApi;
+use Dedoc\Scramble\Support\Generator\SecurityScheme;
+use Illuminate\Support\ServiceProvider;
+
+class DocsServiceProvider extends ServiceProvider
+{
+    public function register()
+    {
+        Scramble::extendOpenApi(function (OpenApi $openApi) {
+            $openApi->secure(
+                SecurityScheme::apiKey('query', 'api_token')
+            );
+        });
+    }
+}
+```
+
+## Examples
+Here are some common examples of the security schemes object you may have in your API. For full list of available methods check implementation of `SecurityScheme` class.
+
+### API Key
+```php
+SecurityScheme::apiKey('query', 'api_token');
+```
+
+### Basic HTTP
+```php
+SecurityScheme::http('basic');
+```
+
+### JWT
+```php
+SecurityScheme::http('bearer', 'JWT');
+```
+
+### Oauth2
+```php
+SecurityScheme::oauth2()
+    ->flow('implicit', function (OAuthFlow $flow) {
+        $flow
+            ->authorizationUrl('https://example.com/api/oauth/dialog')
+            ->addScope('write:pets', 'modify pets in your account');
+    });
+```
diff --git a/src/Support/Generator/OpenApi.php b/src/Support/Generator/OpenApi.php
index 26fdb35c..bf3610db 100644
--- a/src/Support/Generator/OpenApi.php
+++ b/src/Support/Generator/OpenApi.php
@@ -38,6 +38,8 @@ public function setComponents(Components $components)
 
     public function secure(SecurityScheme $securityScheme)
     {
+        $securityScheme->default();
+
         $this->components->addSecurityScheme($securityScheme->schemeName, $securityScheme);
         if ($securityScheme->default) {
             $this->defaultSecurity(new Security($securityScheme->schemeName));
diff --git a/tests/OpenApiBuildersTest.php b/tests/OpenApiBuildersTest.php
index f7a7a920..1e8b2a4e 100644
--- a/tests/OpenApiBuildersTest.php
+++ b/tests/OpenApiBuildersTest.php
@@ -10,7 +10,7 @@
     $openApi = (new OpenApi('3.1.0'))
         ->setInfo(InfoObject::make('API')->setVersion('0.0.1'));
 
-    $openApi->secure(SecurityScheme::apiKey('query', 'api_token')->default());
+    $openApi->secure(SecurityScheme::apiKey('query', 'api_token'));
     $document = $openApi->toArray();
 
     expect($document['security'])->toBe([['apiKey' => []]])
@@ -35,7 +35,6 @@
                     ->tokenUrl('https://test.com/token')
                     ->addScope('wow', 'nice');
             })
-            ->default()
     );
 
     assertMatchesSnapshot($openApi->toArray());