Sitegeist.SchemeOnYou
Always create up-to-date OpenAPI documentation directly from pure, type-safe PHP code
In many projects, we use interfaces to provide data or functions to the website or external partners.
This always raises the question of which data can actually occur, which values are optional, etc. During the creation of software, this is often still intuitive and clear to everyone. However, questions about details often arise during maintenance at the latest, followed by the not always successful search for interface documentation.
The OpenAPI standard has become established in recent years for the documentation of such interfaces. This allows machine-readable documentation to be created. With SwaggerUi, it also offers a human-readable and easy-to-use interface.
If such documentation is precise and really up-to-date, it even allows parts of the source code for using the interface to be generated automatically.
Unfortunately, this is precisely where quality fluctuations have repeatedly occurred in the past - especially with external interfaces. This is particularly problematic because the problem is first analyzed based on the assumption that the documentation is correct. Only after all other options have been ruled out do you start to doubt the documentation.
Having no documentation is bad, but incorrect or incomplete documentation is much worse.
We wanted to avoid this with the interfaces that we create and therefore an internal project was developed at Sitegeist with the following specifications:
- Generate documentation directly from PHP source code or validate existing documentation using the PHP source code
During our research, we looked at a number of existing solutions. What they often had in common was that the documentation was created via comments in the source code. Unfortunately, this meant that there was no protection against discrepancies between the comment and the code. We felt that such a solution was no longer up to date, particularly in view of the latest developments towards type safety in the PHP world. We have therefore supplemented the requirements:
- All information is derived directly from the PHP language and not from annotations, which can deviate.
Unfortunately, this is where the well-trodden path ended and we had to develop the corresponding infrastructure ourselves.
Sitegeist.SchemeOnYou
This package allows you to create Backend endpoints very easily by using methods that accept PHP transfer objects and also return them as a result. The SchemeOnYou package then takes care of the conversion to JSON data and the provision of the documentation.
To make this possible, the PHP transfer objects must adhere to a few rules:
- Readonly classes with constructor promoted public properties as DTO
- Readonly classes with variadic typed constructor arguments as DTO collection
class ProductController extends OpenApiController
{
/*
* Die Methode productListAction ist durch die definition der Typen der Eingabe und Ausgabewerte
* als PHP Objekte strikt definiert und durch statische Anyalyse gut prüfbar
*
* Die Umwandlung der Objekte von / mach JSON und das erstellen der Doku übnernimmz SchemeOnYou
*/
public function productListAction (ProductListQuery $query): ProductList|ProcductListError
{
// business logic
}
}
/*
* Eine DTO Klasse ist readonly und enthält ausschließlich public properties über den
* Konstruktor. Alle Properties müssen DTOs oder DTO-Collections oder simple types sein.
*/
readonly class Product
{
public function __construct (
public ProductIdentifier $identifier,
public string $name,
public Price $price
) {}
}/**
* DTO-Collections sind readonly und haben einen einzigen variadischen Parameter der wiederrum
* einen DTO Typ hat.
*/
readonly class ProductList
{
/**
* @var Product[]
*/
public products;
public function __construct (Product ...$products)
{
$this->products = $products;
}
}Experience
Since the release of SchemeOnYou, all new interfaces that we have created for Neos have been implemented with this system. We already save a lot of time when implementing the actual interface. Even more time is saved when connecting the Frontend applications, as the client code can be autogenerated here. The maintenance of the projects over time is also made easier, as we can statically analyze both the PHP and TypeScript parts. All in all, a big win for everyone involved, who can now focus more on using the data instead of exchanging it.
Go to Sitegeist.SchemeOnYou package
