DRAFT: 2.x renovation - multiple APIs

.gitignore

@@ -1,3 +1,4 @@
+composer.lock
 ###> symfony/framework-bundle ###
 .phpunit.result
 /vendor/

README.md

@@ -7,14 +7,15 @@
 If you’re writing a Swagger API spec and it’s becoming too large, you can split it into multiple files.
 This bundle allows a simple way to split specification files and generate static `index.html` with Swagger UI.
 
-
 ## Installation
 
 ```composer req stfalcon-studio/swagger-bundle```
 
 ### Check the `config/bundles.php` file
 
-By default Symfony Flex will add SwaggerBundle to the `config/bundles.php` file. But in case when you ignored `contrib-recipe` during bundle installation it would not be added. In this case add the bundle manually.
+By default, Symfony Flex will add SwaggerBundle to the `config/bundles.php` file. Though, in case you
+ignored `contrib-recipe` during bundle installation it would not be added. In this case you should add the bundle
+manually.
 
 ```php
 # config/bundles.php
@@ -28,14 +29,21 @@ return [
 
 ## Using
 
-First all we need to set up the folder where the spec is be storing.
-This is the base folder relative for which we will structure the specification files.
+First of all, it's necessary to set up the folders where the spec is stored and where the generated doc must be placed.
+
+The api documentation we write is all inside `config_folder`.
+
+The generated html file is going to be inside `doc_folder`.
+
 ```yaml
 swagger:
-    config_folder: '%kernel.project_dir%/docs/api/'
+  apis:
+    frontend:
+      config_folder: '%kernel.project_dir%/docs/api/frontend/'
+      doc_folder: '%kernel.project_dir%/public/api/frontend/'
 ```
 
-Imagine you have a Swagger spec like this:
+Imagine you are to have a Swagger spec like this:
 
 ```yaml
 openapi: "3.0.0"
@@ -64,20 +72,21 @@ paths:
 Here is our desired folder structure:
 
 ```yaml
-/docs/api/
-     ├── index.yaml
-     ├── paths
-     │   └── user
-     |       └── create-user.yaml
-     │   └── order
-     |       └── create-order.yaml
-     ├── responses
-     │   └── created.yaml
+/docs/api/frontend/
+         ├── index.yaml
+         ├── paths
+         │   └── user
+         |       └── create-user.yaml
+         │   └── order
+         |       └── create-order.yaml
+         ├── responses
+         │   └── created.yaml
 ```
 
-Root file is `index.yaml`. Using `index.yaml` as file name for your root file is a convention. 
+Root file is `index.yaml`. Using `index.yaml` as file name for your root file is a convention.
 
 Here is list of files with their contents:
+
 ### index.yaml
 
 ```yaml
@@ -111,28 +120,29 @@ paths:
       "$responses/created.yaml"
 ```
 
-### paths/responses/created.yaml
+### responses/created.yaml
 
 ```yaml
 '201':
   description: |-
     201 response
 ```
 
-As you can see from the example, in order to specify a folder or file for the include we use the symbol `$` and name.
+As you can see from the example, in order to specify a folder or the included file, `$name` notation is used:
 
 * `$paths` - include all `.yaml` files from folder `paths` (recursively);
-* `$responses/created.yaml` - include the file `created.yaml` that storing in `responses` folder.
+* `$responses/created.yaml` - include the file `created.yaml` from the `responses` folder.
 
 ## Generate Swagger UI
 
 For generating Swagger UI static file use console command:
 
 ```bash
-bin/console assets:install && bin/console swagger:generate-docs
+bin/console assets:install && bin/console swagger:generate-docs frontend
 ```
 
-The file will be saved in the `%kernel.publid_dic%/public/api/index.html` folder and shared at `http://<project>/api/index.html`.
+The file will be saved in the `%kernel.publid_dic%/public/api/frontend/index.html` folder and shared
+at `http://<project>/api/frontend/index.html`.
 
 ## Contributing
 

composer.json

@@ -47,7 +47,7 @@
     "config": {
         "sort-packages": true,
         "allow-plugins": {
-            "symfony/flex": true
+            "symfony/flex": false
         }
     }
 }