pccomponentes/documentation-bundle

PcComponentes Documentation Bundle

v1.4.4 2023-12-20 10:59 UTC

Requires

• php: ^7.4 || ^8.0
• ext-json: *
• pccomponentes/ddd: ^2.0 || ^3.0 || ^4.0
• symfony/config: ^4.4 || ^5.0 || ^6.0 || ^7.0
• symfony/dependency-injection: ^4.4 || ^5.0 || ^6.0 || ^7.0
• symfony/http-foundation: ^4.4 || ^5.0 || ^6.0 || ^7.0
• symfony/http-kernel: ^4.4 || ^5.0 || ^6.0 || ^7.0
• symfony/routing: ^4.4 || ^5.0 || ^6.0 || ^7.0
• symfony/yaml: ^4.4 || ^5.0 || ^6.0 || ^7.0

Requires (Dev)

• pccomponentes/coding-standard: ^1.0
• phpunit/phpunit: ^9
• squizlabs/php_codesniffer: 3.*

MIT

• José Gilberto Mullor

README

The documentation bundle manages the required routes and templates in order to show documentation both in OpenApi and AsyncApi formats.

Installation

Add the pccomponentes/documentation-bundle package to your require section in the composer.json file.

$ composer require pccomponentes/documentation-bundle

Add the DocumentationBundle to your application's kernel.

<?php
public function registerBundles()
{
    $bundles = [
        // ...
        new PcComponentes\DocumentationBundle\DocumentationBundle(),
        // ...
    ];
    ...
}

Depending on your installation, maybe you should add it to the bundles.php file instead.

<?php

return [
    // ...
    PcComponentes\DocumentationBundle\DocumentationBundle::class => ['all' => true],
    // ...
];

Usage

Configure the paths to your YAML files in your config.yml (Both keys are optional).

documentation:
    openapi: 'docs/openapi.yml'
    asyncapi: 'docs/asyncapi.yml'

Enable the paths in your routing.yml file.

documentation:
    resource: '@DocumentationBundle/Resources/config/routing.yaml'
    prefix: /docs

You can choose a prefix where the documentation will be published.

After this, you should be able to see the Swagger interface at /openapi (or /docs/openapi if you used the docs prefix), the AsyncApi at /asyncapi, and all of your event converters at /converters.

Also, you can customize the SwaggerUI options using the key swagger_options, and the AsyncApi ones using asyncapi_options, for example:

documentation:
    openapi: 'docs/openapi.yml'
    asyncapi: 'docs/asyncapi.yml'
    swagger_options:
        deepLinking: true
        displayOperationId: true
        displayRequestDuration: true
    asyncapi_options:
        schemaFetchOptions: '{"method":"GET","mode":"cors"}'
    

In addition, you can add your custom links to the homepage using the links key, here is an example:

documentation:
    links:
        - title: 'Google'
          description: 'You can add some notes for each link'
          url: 'https://www.google.com/'
        - title: 'Contact PcComponentes'
          url: 'https://www.pccomponentes.com/soporte/contactar-con-pccomponentes'