psx/api

Parse and generate API specification formats

v5.0.2 2023-03-19 19:53 UTC

Requires

• php: >=8.0
• nikic/php-parser: ^4.0
• psx/json: ^2.0
• psx/model: ^4.0
• psx/schema: ^4.0
• symfony/cache: ^5.0|^6.0
• symfony/console: ^4.0|^5.0|^6.0
• symfony/yaml: ^4.0|^5.0|^6.0
• twig/twig: ^2.4|^3.0

Requires (Dev)

• phpunit/phpunit: ^8.0
• vimeo/psalm: ^4.0

Apache-2.0

• Christoph Kappestein

• api
• specification
• swagger
• openapi
• raml

README

The API component is the reference implementation of the TypeAPI specification. It provides models to describe an REST API and generate based on those models different outputs. You can create those models either by parsing a TypeAPI or OpenAPI specification or by using PHP Attributes. Based on those models it is then possible to generate i.e. client SDKs.

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(int $id, int $year): \My\Response\Model
    {
        // @TODO implement
    }
    
    #[Post]
    #[Path('/my/endpoint')]
    public function insertModel(\My\Request\Model $model): \My\Response\Model
    {
        // @TODO implement
    }
}

This would be then 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

// reads the TypeAPI specification and generates a specification
$specification = \PSX\Api\Parser\TypeAPI::fromFile('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
$generator = new \PSX\Api\Generator\Client\Php();

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

Generator

Client

• Go
• Java
• PHP
• Typescript

Markup

• Client
• HTML
• Markdown

Spec

• OpenAPI 3.1
• TypeAPI