arekushi/swagger-php-module

Swagger-PHP module adapted for mezzio and laminas.

dev-main 2024-10-06 05:11 UTC

Requires

• php: ~8.1.0 || ~8.2.0 || ~8.3.0
• laminas-api-tools/api-tools-asset-manager: ^1.5
• laminas/laminas-config-aggregator: ^1.7
• mezzio/mezzio: ^3.11
• psr/container: ^1.0||^2.0
• psr/http-server-handler: ^1.0.1
• zircote/swagger-php: ^4.4

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.8
• laminas/laminas-diactoros: ^2.13
• mezzio/mezzio-fastroute: ^3.5
• mezzio/mezzio-laminasviewrenderer: ^2.6
• mezzio/mezzio-problem-details: ^1.6
• phpspec/prophecy-phpunit: ^2.0
• phpunit/phpunit: ^9.5

MIT

• Simon Rodin

README

Description

Swagger PHP module adapted for Mezzio/Laminas.

Requirements

• PHP >8.1
• Mezzio\Template\TemplateRendererInterface

Installation

The preferred way to install this wrapper is through composer.

composer require arekushi/swagger-php-module:dev-main --ignore-platform-reqs

Setup

After installation of the package, you need to complete the following steps to use PHP Swagger module:

1. Add \Genxoft\SwaggerPhpModule\ConfigProvider::class to your config aggregator
2. Add and customize (if necessary) configuration (add file php-swagger.global.php into config/autoload)

<?php
return [
    'swagger_php' => [
        'scanDirs' => [
            __DIR__ . '/module'
        ],
        'jsonUrl' => '/api-oas-docs/json',
    ],
    'routes' => [
        'swagger_php.route.json' => [
            'path' => '/api-oas-docs/json',
            'middleware' => [
                \Genxoft\SwaggerPhpModule\Handler\JsonAction::class,
            ],
            'allowed_methods' => ['GET'],
        ],
        'swagger_php.route.ui' => [
            'path' => '/api-oas-docs/ui',
            'middleware' => [
                \Genxoft\SwaggerPhpModule\Handler\UiAction::class,
            ],
            'allowed_methods' => ['GET'],
        ],
    ],
];

Open Api Swagger 3 example annotation

Api server description

/**
 * @OA\Info(
 *   version="1.0",
 *   title="Application API",
 *   description="Server - Mobile app API",
 *   @OA\Contact(
 *     name="John Smith",
 *     email="[e-mail]",
 *   ),
 * ),
 * @OA\Server(
 *   url="https://example.com/api",
 *   description="main server",
 * )
 * @OA\Server(
 *   url="https://dev.example.com/api",
 *   description="dev server",
 * )
 */
...

Handler annotation

/**
 * @OA\Get(path="/",
 *   summary="Handshake",
 *   tags={"handshake"},
 *   @OA\Parameter(
 *     name="access-token",
 *     in="header",
 *     required=false,
 *     @OA\Schema(
 *       type="string"
 *     )
 *   ),
 *   @OA\Response(
 *     response=200,
 *     description="Returns Hello object",
 *     @OA\MediaType(
 *         mediaType="application/json",
 *         @OA\Schema(ref="#/components/schemas/Hello"),
 *     ),
 *   ),
 * )
 */
class HelloHandler implements RequestHandlerInterface
{
...

Model annotation

/**
 *@OA\Schema(
 *  schema="Hello",
 *  @OA\Property(
 *     property="message",
 *     type="string",
 *     description="Text message"
 *  ),
 *  @OA\Property(
 *     property="time",
 *     type="integer",
 *     description="Server current Unix time"
 *  ),
 *  @OA\Property(
 *     property="date",
 *     type="string",
 *     format="date-time",
 *     description="Server current date time"
 *  )
 *)
 */
class HelloModel
{
...

Screenshot

Donate

LICENSE

This curl wrapper is released under the MIT license.