diff --git a/README.md b/README.md index 4e668ac..fcdb4c9 100644 --- a/README.md +++ b/README.md @@ -3,12 +3,15 @@ The PSX API bundle integrates the [PSX API components](https://phpsx.org/) into Symfony which help to build fully type-safe REST APIs. Basically the bundle provides additional attributes which you -can use at your [controller](#controller) to map HTTP parameters to arguments of your controller. -Based on those attributes and type-hints the bundle is able to generate different artifacts: +can use at your [controller](#controller) to map HTTP parameters to arguments of your controller +and commands to generate based on those attributes and type-hints different artifacts: -* Generate OpenAPI specification without additional attributes * Generate Client SDKs for different languages i.e. TypeScript and PHP + * `php bin/console generate:sdk client-typescript` +* Generate OpenAPI specification without additional attributes + * `php bin/console generate:sdk spec-openapi` * Generate DTO classes using [TypeSchema](https://typeschema.org/) + * `php bin/console generate:model` As you note this bundle is about REST APIs and not related to any PlayStation content, the name PSX was invented way back and is simply an acronym which stands for "**P**HP, **S**QL, **X**ML" @@ -93,43 +96,32 @@ the incoming HTTP request. In the controller we use a fictional `PostService` an but you are complete free to design the controller how you like, for PSX it is only important to map the incoming HTTP request parameters to arguments and to provide a return type. -## Generator +### Raw payload -### Model +We always recommend to generate concrete DTOs to describe the request and response payloads. +If you need a raw payload we provide the following type-hints to receive a raw value. -To generate the model classes for the incoming and outgoing payload this bundle provides -a model generator s. +* `Psr\Http\Message\StreamInterface` + * Receive the raw request as stream `application/octet-stream` +* `PSX\Data\Body\Json` + * Receive the raw request as JSON `application/json` +* `PSX\Data\Body\Form` + * Receive the raw request as form `application/x-www-form-urlencoded` +* `string` + * Receive the raw request as string `text/plain` -``` -php bin/console generate:model -``` - -This commands reads the [TypeSchema](https://typeschema.org/) specification located at `config/typeschema.json` -and writes all model classes to `src/Model`. In general TypeSchema is a JSON specification to describe data models. -The following is an example specification to generate a simple Student model. +For example to write a simple proxy method which returns the provided JSON payload s. -```json +```php +#[Route('/post', methods: ['POST'])] +public function update(#[Body] Json $body): Json { - "definitions": { - "Student": { - "description": "A simple student struct", - "type": "struct", - "properties": { - "firstName": { - "type": "string" - }, - "lastName": { - "type": "string" - }, - "age": { - "type": "integer" - } - } - } - } + return $body; } ``` +## Generator + ### SDK To generate an SDK you can simply run the following command: @@ -150,7 +142,7 @@ select a different type. Through the SDKgen project you have the option to generate also client SDKs for different programming languages, therefor you only need to register at the [SDKgen](https://sdkgen.app/) -website to obtain a client id and secret which you need to set as `psx.sdkgen_client_id` and `psx.sdkgen_client_secret` +website to obtain a client id and secret which you need to set as `psx_api.sdkgen_client_id` and `psx_api.sdkgen_client_secret` at your config. After this you can use one of the following types: * `client-csharp` @@ -170,6 +162,57 @@ php bin/console api:push my_document_name Then you also need to provide a client id and secret for your account. The TypeHub platform basically tracks all changes of the API specification and it is possible to download different SDKs. +### Model + +This bundle also provides a model generator which helps to generate DTOs to describe the +incoming and outgoing payload s. + +``` +php bin/console generate:model +``` + +This commands reads the [TypeSchema](https://typeschema.org/) specification located at `config/typeschema.json` +and writes all model classes to `src/Model`. In general TypeSchema is a JSON specification to describe data models. +The following is an example specification to generate a simple Student model. + +```json +{ + "definitions": { + "Student": { + "description": "A simple student struct", + "type": "struct", + "properties": { + "firstName": { + "type": "string" + }, + "lastName": { + "type": "string" + }, + "age": { + "type": "integer" + } + } + } + } +} +``` + +## Configuration + +The bundle needs the following `psx_api.yaml` configuration: + +```yaml +psx_api: + base_url: 'https://api.acme.com' + sdkgen_client_id: '' + sdkgen_client_secret: '' +``` + +The `base_url` is the absolute url to your API so that you don't need to provide the +base url at your client SDK. + +The `sdkgen_client_id` and `sdkgen_client_secret` are credentials to the [SDKgen](https://sdkgen.app/) app. + ## Technical This bundle tries to not change any Symfony behaviour, for example we use the existing `#[Route]` attribute instead