stfalcon-studio / swagger-bundle
Generate Swagger UI documentation from local files
Installs: 31 873
Dependents: 0
Suggesters: 0
Security: 0
Stars: 6
Watchers: 9
Forks: 1
Type:symfony-bundle
Requires
- php: >=8.2
- ext-ctype: *
- ext-iconv: *
- symfony/asset: ^7.0
- symfony/console: ^7.0
- symfony/finder: ^7.0
- symfony/flex: ^v2.4
- symfony/framework-bundle: ^7.0
- symfony/polyfill-ctype: ^1.28
- symfony/twig-bundle: ^7.0
- symfony/yaml: ^7.0
- twig/twig: ^3.8
Requires (Dev)
- escapestudios/symfony2-coding-standard: ^3.13
- phpstan/phpstan: ^1.10.55
- phpstan/phpstan-doctrine: ^1.3
- phpstan/phpstan-phpunit: ^1.3
- phpstan/phpstan-symfony: ^1.3
- phpunit/phpunit: ^9.5
- symfony/dotenv: ^7.0
- symfony/filesystem: ^7.0
- symfony/phpunit-bridge: ^7.0
- thecodingmachine/phpstan-strict-rules: ^1.0
README
π¦ Creates a Swagger-ui page (something like this) in Symfony application.
Description
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.
# config/bundles.php return [ // other bundles StfalconStudio\SwaggerBundle\SwaggerBundle::class => ['all' => true], // other bundles ];
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.
swagger: config_folder: '%kernel.project_dir%/docs/api/'
Imagine you have a Swagger spec like this:
openapi: "3.0.0" info: title: Simple API overview version: 2.0.0 paths: "/users": get: operationId: CreateUser summary: Create user responses: '201': description: |- 201 response "/orders": post: operationId: CreateOrder summary: Create Order responses: '201': description: |- 201 response
Here is our desired folder structure:
/docs/api/ βββ 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.
Here is list of files with their contents:
index.yaml
openapi: "3.0.0" info: title: Simple API overview version: 2.0.0 paths: "$paths"
paths/user/create-user.yaml
"/users": get: operationId: CreateUser summary: Create user responses: "$responses/created.yaml"
paths/order/create-order.yaml
"/orders": post: operationId: CreateOrder summary: Create Order responses: "$responses/created.yaml"
paths/responses/created.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.
$paths
- include all.yaml
files from folderpaths
(recursively);$responses/created.yaml
- include the filecreated.yaml
that storing inresponses
folder.
Generate Swagger UI
For generating Swagger UI static file use console command:
bin/console assets:install && bin/console swagger:generate-docs
The file will be saved in the %kernel.publid_dic%/public/api/index.html
folder and shared at http://<project>/api/index.html
.
Contributing
Read the CONTRIBUTING file.