psx/api

Parse and generate API specification formats

v7.2.5 2024-12-07 14:21 UTC

Requires

• php: >=8.1
• psx/json: ^3.0
• psx/openapi: ^1.0
• psx/schema: ^7.0
• symfony/cache: ^5.0|^6.0|^7.0
• symfony/console: ^5.0|^6.0|^7.0
• symfony/property-access: ^5.0|^6.0|^7.0
• symfony/yaml: ^5.0|^6.0|^7.0
• twig/twig: ^2.4|^3.0

Requires (Dev)

• phpunit/phpunit: ^9.0
• vimeo/psalm: ^5.0

Apache-2.0

• Christoph Kappestein

• api
• specification
• swagger
• openapi
• raml

README

This library provides an attribute parser to dynamically generate a TypeAPI specification from any controller (code-first). Based on the specification it is then possible to generate client SDKs or an OpenAPI specification.

We provide also a hosted version of this code generator. For more integration options you can also take a look at the SDKgen project which provides a CLI binary or GitHub action to integrate the code generator.

Usage

The root model object is called a Specification which contains Operations and Definitions. Each operation maps to a specific REST API endpoint and the definitions represent the schemas to describe the JSON request or response payload.

Framework

You can use PHP attributes to describe the structure of your endpoints. You can then use the attribute parser (PSX\Api\Parser\Attribute) to automatically generate a specification for your controller. A controller class could then look like:

<?php

class MyController
{
    #[Get]
    #[Path('/my/endpoint/:id')]
    public function getModel(#[Param] int $id, #[Query] int $year): \My\Response\Model
    {
        // @TODO implement
    }
    
    #[Post]
    #[Path('/my/endpoint')]
    public function insertModel(#[Body] \My\Request\Model $model): \My\Response\Model
    {
        // @TODO implement
    }
}

This would be enough for the API component to generate either an OpenAPI specification or a client SDK. Note this library only needs the meta information, if you can get those meta information at your framework in another way you can also implement a custom ParserInterface.

Standalone

Beside the framework integration you can use this component also to simply parse existing TypeAPI specification and generate specific output. The following is a simple example how to use the PHP API and how to generate code.

<?php

// use the API manager to obtain a specification from different sources
$manager = new \PSX\Api\ApiManager(new \PSX\Schema\SchemaManager());

// reads the TypeAPI specification and generates a specification
$specification = $manager->getApi('./typeapi.json');

// contains all schema type definitions
$definitions = $specification->getDefinitions();

// returns the resource foo from the specification
$operation = $specification->getOperations()->get('my.operation');

// returns all available arguments
$operation->getArguments();

// returns the return type
$operation->getReturn();

// returns all exceptions which are described
$operation->getThrows();

// returns the assigned HTTP method
$operation->getMethod();

// returns the assigned HTTP path
$operation->getPath();

// creates a PHP client which consumes the defined operations
$registry = \PSX\Api\GeneratorFactory::fromLocal()->factory();
$generator = $registry->getGenerator(\PSX\Api\Repository\LocalRepository::CLIENT_PHP)

$source = $generator->generate($resource);