PHPackages                             ehyiah/apidoc-bundle - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. ehyiah/apidoc-bundle

ActiveSymfony-bundle[API Development](/categories/api)

ehyiah/apidoc-bundle
====================

Symfony Bundle to deal with api doc using SwaggerUI and yaml/yml/php-classes files

1.0.0(4mo ago)24301[2 issues](https://github.com/Ehyiah/ApiDocBundle/issues)MITPHPPHP >=8.1CI failing

Since May 31Pushed 4mo ago1 watchersCompare

[ Source](https://github.com/Ehyiah/ApiDocBundle)[ Packagist](https://packagist.org/packages/ehyiah/apidoc-bundle)[ RSS](/packages/ehyiah-apidoc-bundle/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (18)Versions (15)Used By (0)

 [![Melody logo](./logo.png)](./logo.png)

ApiDocBundle
============

[](#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
----------

[](#-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
-------------------

[](#-table-of-contents)

- [Installation](#installation)
- [Configuration](#configuration)
    - [UI Selection](#ui-selection)
- [Usage](#usage)
    - [1. YAML Configuration](#1-yaml-configuration)
    - [2. PHP Configuration](#2-php-configuration-classes)
    - [3. IDE Integration](#3-ide-integration)
- [Component Generation](#component-generation)

---

Installation
------------

[](#installation)

### 1. Allow Contrib Recipes

[](#1-allow-contrib-recipes)

Ensure Symfony Flex allows contrib recipes:

```
composer config extra.symfony.allow-contrib true
```

### 2. Install the Bundle

[](#2-install-the-bundle)

```
composer require ehyiah/apidoc-bundle
```

---

Configuration
-------------

[](#configuration)

### 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

[](#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
------------

[](#ui-selection)

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

UIValueDescriptionTry it outLinks**Swagger UI**`swagger`The standard, widely used✅ Yes[GitHub](https://github.com/swagger-api/swagger-ui) - [Demo](https://petstore.swagger.io/)**Redoc**`redoc`Clean, elegant 3-column layout❌ No[GitHub](https://github.com/Redocly/redoc) - [Demo](https://redocly.github.io/redoc/)**Stoplight Elements**`stoplight`Modern, customizable✅ Yes[GitHub](https://github.com/stoplightio/elements) - [Demo](https://elements-demo.stoplight.io/)**RapiDoc**`rapidoc`Lightweight, dark/light themes✅ Yes[GitHub](https://github.com/rapi-doc/RapiDoc) - [Demo](https://rapidocweb.com/examples.html)**Scalar**`scalar`Beautiful, modern design✅ Yes[GitHub](https://github.com/scalar/scalar) - [Demo](https://docs.scalar.com/swagger-editor)### Switching UI On-the-Fly

[](#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
-----

[](#usage)

### 1. YAML Configuration

[](#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

[](#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`:**

```