Auto-Generate from an OpenApi definition

OpenApi is the world's largest framework of API developer tools for the OpenAPI Specification(OAS), enabling development across the entire API lifecycle, from design and documentation, to test and deployment.

Restserver supports both specifications 2.0 (former Swagger) and 3.0.

There are several tools for create and maintain the definition. Once you're using this concept/methodology you can apply here and generate automatically the routes without duplicate your work.

First you need to create a swagger.json file (a .yaml or .yml file is also accepted). The "operationId" must have the Namespace\\Class::method like the example below:

{
  ...
  "paths": {
    "/pet": {
      "post": {
        "summary": "Add a new pet to the store",
        "description": "",
        "operationId": "PetStore\\Pet::addPet"
      }
    }
  }
  ...
}

We recommend you use the zircote/swagger-php tool to generate automatically your JSON file from PHPDocs comments.

In that case the operationId will be generated automatically. The format will be: HTTP_METHOD::PATH::Namespace\\Class::method (e.g. GET::/pet::PetStore\\Pet::getPet)

vendor/bin/openapi -c operationid.hash=false src

After you have the proper swagger.json just call the Server and set automatic routes:

<?php

require_once __DIR__ . '/../vendor/autoload.php';

use ByJG\RestServer\Server;
use ByJG\RestServer\Route\OpenApiRouteList;

$routeDefinition = new OpenApiRouteList(__DIR__ . '/swagger.json');

$restServer = new Server();
$restServer->handle($routeDefinition);

Customizing the Handlers

The OpenApi specificy the proper output encoding. We can override the default output processor for a specific route or mime type.

Mime Type

<?php
$routeDefinition = new \ByJG\RestServer\Route\OpenApiRouteList(__DIR__ . '/swagger.json');
$routeDefinition->withOutputProcessorForMimeType(
    "application/json",
    \ByJG\RestServer\OutputProcessor\JsonCleanOutputProcessor::class
);

Default Processor

Routes that do not declare any content type use JsonOutputProcessor. To change it:

<?php
$routeDefinition->withDefaultProcessor(\ByJG\RestServer\OutputProcessor\XmlOutputProcessor::class);

Specific Route

The path must include the schema base path (basePath, or the path of the first servers URL), if any.

<?php
$routeDefinition = new \ByJG\RestServer\Route\OpenApiRouteList(__DIR__ . '/swagger.json');
$routeDefinition->withOutputProcessorForRoute(
    "GET",
    "/pet/{petId}",
    \ByJG\RestServer\OutputProcessor\JsonOutputProcessor::class
);

Content negotiation from OpenAPI metadata

Starting with the recent OpenApiRouteList changes, the generator inspects either the legacy produces array or the OpenAPI 3 responses[200].content map to determine which output processors a route should use. When a single content type is declared, the corresponding processor is wired automatically. When multiple content types are listed, the route stores an array of processors and the runtime picks the best one according to the incoming Accept header.

You can still call withOutputProcessorForRoute() or withOutputProcessorForMimeType() to override the defaults, but most use cases can now be described solely in the OpenAPI document.