Download the PHP package ehyiah/apidoc-bundle without Composer

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:

2. Install the Bundle

Configuration

Bundle Configuration

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

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:

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:

💡 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.

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).