PHPackages                             rafoabbas/api-docs - 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. [HTTP & Networking](/categories/http)
4. /
5. rafoabbas/api-docs

ActiveLibrary[HTTP & Networking](/categories/http)

rafoabbas/api-docs
==================

Generate API documentation (Postman collections & OpenAPI specs) from PHP attributes and YAML files

v0.6.0(2mo ago)23163MITPHPPHP ^8.1CI passing

Since Jan 29Pushed 2mo agoCompare

[ Source](https://github.com/rafoabbas/api-docs)[ Packagist](https://packagist.org/packages/rafoabbas/api-docs)[ Docs](https://github.com/rafoabbas/api-docs)[ RSS](/packages/rafoabbas-api-docs/feed)WikiDiscussions main Synced 2w ago

READMEChangelogDependencies (18)Versions (11)Used By (0)

API Docs
========

[](#api-docs)

Generate API documentation (Postman collections & OpenAPI specs) from PHP 8 attributes and YAML files.

Requirements
------------

[](#requirements)

- PHP 8.2+
- Laravel 11+

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

[](#installation)

```
composer require rafoabbas/api-docs
```

Quick Start
-----------

[](#quick-start)

### Option 1: YAML Definitions (Recommended)

[](#option-1-yaml-definitions-recommended)

Define API endpoints in YAML files under `resources/api-docs/`:

```
# resources/api-docs/auth.yaml
folder: V1 / Auth

auth:
  type: bearer

requests:
  - name: Login
    method: POST
    uri: /v1/auth/login
    description: Authenticate user
    auth:
      type: noauth
    body:
      phone: "905551234567"
      password: "secret123"
    variables:
      - name: BEARER_TOKEN
        path: data.token

  - name: Get Profile
    method: GET
    uri: /v1/auth/me
    resource: App\Http\Resources\UserResource
```

### Option 2: PHP Attributes

[](#option-2-php-attributes)

Add attributes to your controller:

```
use ApiDocs\Attributes\ApiFolder;
use ApiDocs\Attributes\ApiRequest;

#[ApiFolder('V1 / Auth')]
class AuthController extends Controller
{
    #[ApiRequest(name: 'Login', description: 'Authenticate user')]
    public function login(LoginRequest $request): JsonResponse
    {
        // ...
    }
}
```

### Generate Documentation

[](#generate-documentation)

```
php artisan api:generate
```

Output (when `variable_scope` is `collection`):

```
docs/
├── postman/
│   └── {timestamp}-collection.json
└── openapi/
    └── {timestamp}-openapi.yaml

```

Output (when `variable_scope` is `environment`):

```
docs/
├── postman/
│   ├── {timestamp}-collection.json
│   └── {timestamp}-local.postman_environment.json
└── openapi/
    └── {timestamp}-openapi.yaml

```

Command Options
---------------

[](#command-options)

```
php artisan api:generate --format=postman      # Only Postman
php artisan api:generate --format=openapi      # Only OpenAPI
php artisan api:generate --format=both         # Both (default)
php artisan api:generate --name="My API"       # Custom name
php artisan api:generate --output=api-docs     # Custom output dir
php artisan api:generate --openapi-format=json # OpenAPI as JSON
php artisan api:generate --exclude=admin       # Exclude prefixes
```

Attributes
----------

[](#attributes)

AttributeDescription`ApiRequest`Request name, description, order`ApiFolder`Group requests into folders`ApiBody`Request body (supports FormRequest merge)`ApiResource`Response Resource class`ApiVariable`Extract response values to variables`ApiHeader`Custom headers`ApiQueryParam`Query parameters`ApiAuth`Authentication config`ApiResponse`Example responses`ApiTest`Postman test scripts`ApiPreRequest`Pre-request scripts`ApiHidden`Exclude from docs`ApiDeprecated`Mark endpoints as deprecatedAuto-Resolve Features
---------------------

[](#auto-resolve-features)

- **Request body** from FormRequest `rules()`
- **Query parameters** from FormRequest `rules()` (for GET/DELETE requests)
- **Response structure** from Resource `toArray()`
- **Authentication** from middleware (`auth:sanctum`, `auth`)
- **Route parameters** from URI (`{id}` → `:id`)
- **OpenAPI schema** from validation rules (`required|email` → `type: string, format: email`)
- **PHP Enum** to OpenAPI enum conversion (via `Rule::in()` or `Enum` rule)
- **File upload** auto-detection (`file`, `image`, `mimes:` → `multipart/form-data`)
- **Pagination** auto-detection (`paginate()` → paginated response schema)

Merging Strategy
----------------

[](#merging-strategy)

YAML and PHP attributes can be used together. When both define the same endpoint (matched by `method + uri`):

- **YAML definitions take priority** over PHP attributes
- Merge is done field-by-field (non-null YAML fields override attribute fields)
- Unmatched requests from both sources are included
- YAML `body_merge` and `body_except` allow merging YAML body with auto-resolved FormRequest body

This allows a YAML-first workflow where controllers stay clean and all API documentation lives in YAML files.

Swagger UI
----------

[](#swagger-ui)

Interactive API documentation is available at `/api/docs` by default.

```
// config/api-docs.php
'swagger' => [
    'enabled' => true,
    'path' => '/api/docs',
    'middleware' => [],
    'dark_mode' => true,
    'persist_authorization' => true,
    'token' => env('API_DOCS_SWAGGER_TOKEN'),
],
```

**Endpoints:**

- `/api/docs` - Swagger UI interface
- `/api/docs/openapi.json` - OpenAPI specification

**Protect with token:**

```
API_DOCS_SWAGGER_TOKEN=your-secret-token
```

Access: `/api/docs?token=your-secret-token`

**Disable in production:**

```
API_DOCS_SWAGGER_ENABLED=false
```

Documentation
-------------

[](#documentation)

Full documentation is available on the **[Wiki](https://github.com/rafoabbas/api-docs/wiki)**:

- [Configuration](https://github.com/rafoabbas/api-docs/wiki/Configuration)
- [Attributes](https://github.com/rafoabbas/api-docs/wiki/Attributes)
- [YAML Definitions](https://github.com/rafoabbas/api-docs/wiki/YAML-Definitions)
- [Auto-Resolve](https://github.com/rafoabbas/api-docs/wiki/Auto-Resolve)

Roadmap
-------

[](#roadmap)

### Completed

[](#completed)

- Swagger UI integration - Interactive docs at `/api/docs`
- Query parameter auto-resolve from FormRequest for GET/DELETE requests
- Class-level `ApiPreRequest` support
- YAML-first workflow with priority merge
- YAML `resource` support for auto-resolving response from Resource classes
- YAML `body_merge` / `body_except` for merging with FormRequest body
- YAML `hidden` support to exclude requests from docs
- YAML file-level shared `auth`, `headers`, `pre_request_scripts`
- Configurable `variable_scope` (`collection` or `environment`)
- Validation rules to OpenAPI schema (`required|email` → `type: string, format: email`)
- PHP Enum to OpenAPI enum conversion (via `Rule::in()` or `Enum` validation rule)
- `#[ApiDeprecated]` - Mark endpoints as deprecated (with reason and replacement)
- Pagination auto-detect (`paginate()` → paginated response schema with links/meta)
- File upload - Auto multipart/form-data support (`file`, `image`, `mimes:` rules)

### Export Formats

[](#export-formats)

- Markdown export
- Insomnia export format
- Bruno export format
- Postman Cloud sync

### Schema & Validation

[](#schema--validation)

- JSON:API specification support

### Attributes

[](#attributes-1)

- `#[ApiRateLimit]` - Document rate limits
- `#[ApiWebhook]` - Webhook documentation

### Auto-Detection

[](#auto-detection)

- Factory examples - Generate example data from Laravel factories

### Authentication

[](#authentication)

- OAuth2 flows documentation
- Multiple auth schemes per endpoint

### UI & Visualization

[](#ui--visualization)

- ReDoc UI - Alternative documentation UI
- Scalar UI - Modern API documentation (scalar.com)
- Code snippets - curl, JavaScript, Python, PHP examples
- API changelog - Version diff documentation

### Versioning

[](#versioning)

- API versioning - Separate specs for v1, v2, etc.

License
-------

[](#license)

MIT

###  Health Score

39

—

LowBetter than 85% of packages

Maintenance83

Actively maintained with recent releases

Popularity18

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity40

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 97.3% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~6 days

Recently: every ~12 days

Total

10

Last Release

88d ago

PHP version history (2 changes)v0.1.0PHP ^8.2

v0.6.0PHP ^8.1

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/66231852?v=4)[raufabbas](/maintainers/raufabbas)[@RaufAbbas](https://github.com/RaufAbbas)

---

Top Contributors

[![rafoabbas](https://avatars.githubusercontent.com/u/32704040?v=4)](https://github.com/rafoabbas "rafoabbas (36 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (1 commits)")

---

Tags

apilaravelrestdocumentationswaggeropenapiattributesPostman

###  Code Quality

TestsPest

Static AnalysisRector

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/rafoabbas-api-docs/health.svg)

```
[![Health](https://phpackages.com/badges/rafoabbas-api-docs/health.svg)](https://phpackages.com/packages/rafoabbas-api-docs)
```

###  Alternatives

[api-platform/laravel

API Platform support for Laravel

59156.3k11](/packages/api-platform-laravel)[noitran/opendox

OpenApi(Swagger) 3.0 package for Lumen 5.5+ and Laravel 5.5+ with REDOC UI and SwaggerUI 3

2214.2k](/packages/noitran-opendox)[tartanlegrand/laravel-openapi

Generate OpenAPI Specification for Laravel Applications

38201.0k2](/packages/tartanlegrand-laravel-openapi)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)