VOOZH about

URL: http://zircote.com/swagger-php/

⇱ Swagger-PHP

Skip to content

Swagger-PHP

Generate OpenAPI documentation for your RESTful API.

OpenAPI conformant

Generate OpenAPI documents in version 3.0 or 3.1.

Document your API inside PHP source code

Using swagger-php lets you write the API documentation inside the PHP source files which helps keeping the documentation up-to-date.

Annotation and Attribute support

Annotations can be either docblocks or PHP 8.1 attributes.

1. Install with composer: ​

shell
> composer require zircote/swagger-php

2. Update your code ​

Add swagger-php attributes (or legacy annotations) to your source code.

⚠️ The doctrine/annotations library used to parse annotation is going to be deprecated, so wherever possible attributes should be used.

php
<?php

namespace Openapi\Snippets\MinimalApi;

use OpenApi\Attributes as OA;

#[OA\Info(title: 'My First API', version: '0.1')]
class OpenApi
{
}

class MyController
{
 #[OA\Get(path: '/api/data.json', operationId: 'getData')]
 #[OA\Response(response: '200', description: 'The data')]
 public function getResource()
 {
 // ...
 }
}
php
<?php

namespace Openapi\Snippets\MinimalApi;

use OpenApi\Annotations as OA;

/**
 * @OA\Info(
 * title="My First API",
 * version="0.1"
 * )
 */
class OpenApi
{
}

class MyController
{
 /**
 * @OA\Get(
 * path="/api/data.json",
 * operationId="getData",
 * @OA\Response(
 * response="200",
 * description="The data"
 * )
 * )
 */
 public function getResource()
 {
 // ...
 }
}

3. Generate OpenAPI documentation ​

shell
> ./vendor/bin/openapi src -o openapi.yaml

4. Explore and interact with your API ​

Use an OpenAPI tool like Swagger UI or Scalar to explore and interact with your API.

Links ​