README

ApiDocBundle

A Symfony Bundle to generate and display API documentation using OpenAPI (Swagger) v3. Define your documentation using YAML files, PHP classes, or a mix of both!

✨ Features

• Multiple UIs supported: Swagger UI, Redoc, Stoplight Elements, RapiDoc, and Scalar.
• Flexible Configuration: Use YAML files, PHP classes, or both.
• Generator Commands: CLI tools to quickly generate Schemas, Request Bodies, and Routes.
• Hybrid Support: Seamlessly merge YAML and PHP definitions.
• Attributes Support: Link your Controllers to their documentation for easy IDE navigation.

???? Table of Contents

• Installation
• Configuration
  • UI Selection
• Usage
  • 1. YAML Configuration
  • 2. PHP Configuration
  • 3. IDE Integration
• Component Generation

Installation

1. Allow Contrib Recipes

Ensure Symfony Flex allows contrib recipes:

composer config extra.symfony.allow-contrib true

2. Install the Bundle

composer require ehyiah/apidoc-bundle

Configuration

Bundle Configuration

The default configuration is automatically installed in config/packages/ehyiah_api_doc.yaml.

# config/packages/ehyiah_api_doc.yaml
ehyiah_api_doc:
    # Select your preferred UI
    ui: swagger  # Options: swagger, redoc, stoplight, rapidoc, scalar

    # Directory where YAML files are located (and where commands look for existing files)
    source_path: 'src/Swagger'

    # Directory to dump generated files
    dump_path: 'src/Swagger/dump'

    # Directories to scan for Entity generation
    scan_directories:
        - 'src/Entity'

Custom URL

The documentation is available at /ehyiah/api/doc by default. You can customize this route in config/routes/ehyiah_api_doc.yaml.

UI Selection

You can choose from 5 modern UIs to display your documentation.

Switching UI On-the-Fly

You can switch the interface dynamically using the ui query parameter:

• https://your-domain/ehyiah/api/doc?ui=redoc
• https://your-domain/ehyiah/api/doc?ui=scalar

Usage

1. YAML Configuration

Place your OpenAPI YAML files in the directory defined by source_path (default: src/Swagger). The bundle will automatically parse and merge all .yaml and .yml files in this folder.

Example src/Swagger/info.yaml:

documentation:
    openapi: 3.0.0
    info:
        title: My Awesome API
        description: API documentation
        version: 1.0.0
    servers:
        - url: https://api.example.com
          description: Production server
    components:
        securitySchemes:
            Bearer:
                type: http
                scheme: bearer
                bearerFormat: JWT

2. PHP Configuration Classes

You can define your documentation programmatically using PHP classes. This offers strong typing and IDE autocompletion.

1. Create a class that implements Ehyiah\ApiDocBundle\Interfaces\ApiDocConfigInterface.
2. Implement the configure method.
3. Your class is automatically autoloaded and parsed.

Example src/ApiDoc/UserDocConfig.php:

<?php
namespace App\ApiDoc;

use Ehyiah\ApiDocBundle\Builder\ApiDocBuilder;
use Ehyiah\ApiDocBundle\Interfaces\ApiDocConfigInterface;

class UserDocConfig implements ApiDocConfigInterface
{
    public function configure(ApiDocBuilder $builder): void
    {
        $builder
            ->addRoute()
                ->path('/api/users/{id}')
                ->method('GET')
                ->summary('Get user by ID')
                ->tag('Users')
                ->response(200)
                    ->description('User details')
                    ->jsonContent()
                        ->ref('#/components/schemas/User')
                    ->end()
                ->end()
            ->end();
    }
}

???? Tip: While PHP config classes can be placed anywhere in src/, it is recommended to keep them in src/Swagger (or your source_path) if you want the Generator Commands to detect them and prevent duplicates.

???? Read full PHP Config Documentation ???? Read the PHP Builder Reference

3. IDE Integration

Link your Controller methods to their documentation using the #[ApiDoc] attribute. This allows you to Ctrl+Click from your Controller directly to the documentation source.

use Ehyiah\ApiDocBundle\Attributes\ApiDoc;
use App\ApiDoc\UserDocConfig;

class UserController
{
    #[ApiDoc(UserDocConfig::class)]
    public function getUser(int $id) { /* ... */ }
}

Component Generation

This bundle provides CLI commands to help you kickstart your documentation by generating reusable OpenAPI components.

Command Options

???? Read the Full Guide on References

Duplicate Detection

The commands are smart! They check if a component with the same name already exists:

• Same Format: Warns you and shows a diff before overwriting.
• Cross Format: Warns you if you try to generate a YAML component when a PHP version already exists (and vice-versa).

Linting & Exporting

You can export your entire documentation to a single JSON or YAML file, which is useful for CI/CD linting (e.g., using vacuum).

  # Export to JSON
  bin/console apidocbundle:api-doc:generate --format=json
  
  # Export to YAML
  bin/console apidocbundle:api-doc:generate --format=yaml