stfalcon-studio/swagger-bundle

Generate Swagger UI documentation from local files

v1.0.0 2024-02-11 20:52 UTC

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

MIT

• symfony
• bundle
• swagger
• openapi

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 folder paths (recursively);
• $responses/created.yaml - include the file created.yaml that storing in responses 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.