PHPackages                             zircote/swagger-php - 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. zircote/swagger-php

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

zircote/swagger-php
===================

Generate interactive documentation for your RESTful API using PHP attributes (preferred) or PHPDoc annotations

6.0.6(2mo ago)5.3k132.9M—4%939[14 issues](https://github.com/zircote/swagger-php/issues)[3 PRs](https://github.com/zircote/swagger-php/pulls)20Apache-2.0PHPPHP >=8.2CI passing

Since Apr 1Pushed 2w ago92 watchersCompare

[ Source](https://github.com/zircote/swagger-php)[ Packagist](https://packagist.org/packages/zircote/swagger-php)[ Docs](https://github.com/zircote/swagger-php)[ GitHub Sponsors](https://github.com/zircote)[ RSS](/packages/zircote-swagger-php/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (26)Versions (207)Used By (20)

[![Build Status](https://camo.githubusercontent.com/15089156542f5f9c0a41a0dfb7df2df9056f77131ca73de6230dde0736ab3c0f/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f7a6972636f74652f737761676765722d7068702f6275696c642e796d6c3f6272616e63683d6d6173746572)](https://github.com/zircote/swagger-php/actions?query=workflow:build)[![Total Downloads](https://camo.githubusercontent.com/c2bb8bad151ca8f49df80908c1e6e796a05367f6df7a65864c87e5f4d9ba9231/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f7a6972636f74652f737761676765722d7068702e737667)](https://packagist.org/packages/zircote/swagger-php)[![License](https://camo.githubusercontent.com/caca0ef5422f17fb90c77a2f0bb083a8f8a4c71d2eb9545ef04ff01b00d7be62/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d417061636865322e302d626c75652e737667)](LICENSE)

swagger-php
===========

[](#swagger-php)

Generate interactive [OpenAPI](https://www.openapis.org) documentation for your RESTful API using [PHP attributes](https://www.php.net/manual/en/language.attributes.overview.php) (preferred) or [doctrine annotations](https://www.doctrine-project.org/projects/annotations.html) (requires additional `doctrine/annotations` library).

See the [documentation website](https://zircote.github.io/swagger-php/guide/using-attributes.html) for supported attributes and annotations.

**Annotations are deprecated and may be removed in a future release of swagger-php.**

Features
--------

[](#features)

- Compatible with the OpenAPI **3.0**, **3.1** and **3.2** specification.
- Extracts information from code and existing phpdoc comments.
- Can be used programmatically or via command-line tool.
- [Documentation site](https://zircote.github.io/swagger-php/) with a getting started guide.
- Error reporting (with hints, context).
- All metadata is configured via PHP attributes.

OpenAPI version support
-----------------------

[](#openapi-version-support)

`swagger-php` allows to generate specs either for **OpenAPI 3.0.0**, **OpenAPI 3.1.0** and **OpenAPI 3.2.0**. By default, the spec will be in version `3.0.0`. The command line option `--version` may be used to change to any other supported version.

Programmatically, the method `Generator::setVersion()` can be used to change the version.

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

[](#requirements)

`swagger-php` requires at least **PHP 8.2**.

Installation (with [Composer](https://getcomposer.org))
-------------------------------------------------------

[](#installation-with-composer)

```
composer require zircote/swagger-php
```

For cli usage from anywhere, install swagger-php globally and make sure to place the `~/.composer/vendor/bin` directory in your PATH so the `openapi` executable can be located by your system.

```
composer global require zircote/swagger-php
```

### doctrine/annotations

[](#doctrineannotations)

As of version `4.8` the [doctrine annotations](https://www.doctrine-project.org/projects/annotations.html) library **is optional** and **no longer installed by default**.

If your code uses doctrine annotations you will need to install that library manually:

```
composer require doctrine/annotations
```

Usage
-----

[](#usage)

Use OpenAPI attributes to add metadata to your classes, methods and other structural PHP elements.

```
use OpenApi\Attributes as OAT;

#[OAT\Info(title: 'My First API', version: '0.1')]
class MyApi
{
    #[OAT\Get(path: '/api/resource.json')]
    #[OAT\Response(response: '200', description: 'An example resource')]
    public function getResource()
    {
        // ...
    }
}
```

Visit the [Documentation website](https://zircote.github.io/swagger-php/) for the [Getting started guide](https://zircote.github.io/swagger-php/guide) or look at the [examples directory](docs/examples) for more examples.

### Usage from PHP

[](#usage-from-php)

Generate always-up-to-date documentation.

```