PHPackages                             pswag/pswag - 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. pswag/pswag

ActiveLibrary[API Development](/categories/api)

pswag/pswag
===========

Code-first REST API and Swagger generation for PHP

1.0.3(3mo ago)11931MITPHP

Since Aug 28Pushed 3mo ago1 watchersCompare

[ Source](https://github.com/lnaegele/PSwag)[ Packagist](https://packagist.org/packages/pswag/pswag)[ RSS](/packages/pswag-pswag/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (4)Dependencies (3)Versions (5)Used By (1)

PSwag - code-first REST API and Swagger generation for PHP
==========================================================

[](#pswag---code-first-rest-api-and-swagger-generation-for-php)

Easily create a REST API for your PHP functions - same way as you might know from ABP framework's application services - without the need to juggle with Requests and Responses anymore. All you need to do is providing proper type definitions for method parameters and return types of your endpoint functions.

While many api-first approaches exist that generate server-side code from a predefined OpenAPI specification, or derive this from a proprietary documentation as extension to code, the project PSwag aims at code-first and auto generation (on the fly) of swagger endpoints by relying on code directly that just needs to be properly typed.

PSwag is an extension to Slim and you can use all functionalities of it. In addition to this, PSwag brings you following benefits:

- It automatically maps your custom method signatures to REST API endpoints
- It provides an always-up-to-date OpenAPI 3.0 specification of your REST API endpoints
- It embeds Swagger UI
- It supports GET, PUT, DELETE, PATCH, POST
- It supports PHP inbuilt types, enums, custom classes, arrays (of both, inbuilt and custom types), nullables
- Code annotations are directly used to show as descriptions in Swagger
- When calling a REST endpoint, the request is automatically transformed and mapped PHP method is invoked
- The return result of PHP method is automatically transformed to REST result and returned to endpoint caller
- Authentication is supported for BasicAuth, Bearer and API Keys

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

[](#installation)

It's recommended that you use Composer to install PSwag.

`$ composer require pswag/pswag`

This will install PSwag and all required dependencies.

Basic example: Petstore
-----------------------

[](#basic-example-petstore)

Let's create an example for a Petstore. To specify an endpoint for our REST API, first create a method `getPetById` that takes an id and returns an object of type `Pet`.

```
class PetApplicationService
{
    /**
     * Find pet by ID
     * @param int $petId ID of pet to return
     * @return Pet Returns a single pet
     */
    public function getPetById(int $petId): Pet {
        return new Pet(10, 'doggie', new Category(1, 'Dog'), ['photo1.jpg'], [new Tag(0, 'cute')], 'available');
    }
}
```

Note that all parameters and also return type need to be properly typed in order to enable PSwag to derive the OpenAPI specification. Method comments can be used to provide descriptions or more specific datatypes.

When using custom types, e.g. classes `Pet`, `Category` and `Tag`, all of their properties need to be typed as well. Let's have a look at class `Pet`:

```
class Pet
{
    public ?int $id;

    public string $name;

    public ?Category $category;

    /** @var string[] $photoUrls */
    public array $photoUrls;

    /** @var ?PSwag\Example\Application\Dtos\Tag[] $tags */
    public ?array $tags;

    public ?string $status;
}
?>
```

For `$photoUrls` the type `array` is not sufficient. In such cases, its unique datatype can be specified as annotation with `/** @var string[] $photoUrls */`. Now, PSwag knows how to use it for endpoints. Same applies to `$tags`, but in addition there is a custom class used as array.

Please note:

- When not in the same namespace as `Pet`, class `Tag` must be referenced with fully qualified namespace in order to be resolvable by PSwag.
- If your model contains data fields that are not meant to be exposed, or inherited classes contain properties that are not sufficient to be converted to an OpenAPI specification, it is considered best practice to create a dedicated dto (data transfer object) class that contains intentional properties only, to use this dto type in API signature instead and to map between your model and this dto type.

Finally, create a Slim application in index.php and register method `getPetById` to it:

```