Merge pull request #25 from DoclerLabs/fix-nullable

Fix nullable

Author: vsouz4

.php_cs.php

@@ -65,6 +65,9 @@
     'binary_operator_spaces'                    => [
         'default' => 'align_single_space_minimal',
     ],
+    'no_superfluous_phpdoc_tags'                => true,
+    'no_empty_phpdoc'                           => true,
+    'no_extra_blank_lines'                      => true,
 ];
 
 return Config::create()

CHANGELOG.md

@@ -4,6 +4,17 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+## [4.1.0] - 2020-12-28
+### Fixed
+ - Nullable mandatory DateTime properties in schema now work correctly without doing `new DateTimeImmutable(null)`
+ - Proper nullable typehint and default value in properties for 7.4 schemas to avoid non initialized errors
+
+### Changed
+ - Changed default php-cs-fixer configuration to remove superfluous docblocks, to improve generated code readability
+
+### Added
+ - Makefile with standard routines to easy development / contribution (run tests, analyse code, fix code style)
+
 ## [4.0.0] - 2020-11-26
 ### Changed
  - Guzzle 6/7 dependency removed altogether in favor of PSR-18 interfaces for Http Client

CONTRIBUTING.md

@@ -28,10 +28,10 @@ If you're opening a PR, keep in mind Github will validate code style (PSR1/PSR2)
 
 This generator works with PHP 7.4 so either you need to have it locally installed or you can use any php 7.4 docker image to run phpunit, phpstan, php-cs-fixer etc.
 
-To make sure your code is following the correct style, run:
+To make sure your code is following the correct style, run (or check `make` to run these tasks through php 7.4 docker image):
 
 ```
-$ ./vendor/bin/php-cs-fixer fix src
+$ ./vendor/bin/php-cs-fixer fix .
 ```
 
 To statically analyse your code, run:
@@ -46,6 +46,24 @@ To run tests:
 $ ./vendor/bin/phpunit
 ```
 
+After doing your changes, you can validate it by using your modified generator with an actual Open API specification file. To do that, you must generate your own local Docker image of this generator and use it with any spec you may have:
+
+```
+$ docker build -t my-api-client-generator .
+```
+
+Then run the same command to build your API client but replacing `dhlabs/api-client-generator` with `my-api-client-generator`. For example:
+```
+docker run -it \
+-v {path-to-specification}/openapi.yaml:/openapi.yaml:ro \
+-v {path-to-client}/some-api-client:/client \
+-e NAMESPACE=Group\\SomeApiClient \
+-e OPENAPI=/openapi.yaml \
+-e OUTPUT_DIR=/client \
+-e PACKAGE=group/some-api-client \
+my-api-client-generator
+```
+
 ## Community
 
 Discussions must take place on this repository's [Issues](https://github.com/DoclerLabs/api-client-generator/issues) and [Pull Requests](https://github.com/DoclerLabs/api-client-generator/pulls) sections. Anybody is welcome to join these conversations.

Makefile

@@ -0,0 +1,17 @@
+.PHONY: $(filter-out help, $(MAKECMDGOALS))
+.DEFAULT_GOAL := help
+
+DOCKER_RUN=docker run -w /app -v $(shell pwd):/app php:7.4-cli-alpine php
+
+help:
+	@echo "\033[33mUsage:\033[0m\n  make [target] [arg=\"val\"...]\n\n\033[33mTargets:\033[0m"
+	@grep -E '^[a-zA-Z0-9_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[32m%-10s\033[0m %s\n", $$1, $$2}'
+
+test: ## run test suites
+	$(DOCKER_RUN) vendor/bin/phpunit -c phpunit.xml.dist --colors=always
+
+cs: ## fix code style
+	$(DOCKER_RUN) vendor/bin/php-cs-fixer fix .
+
+stan: ## statically analyse code
+	$(DOCKER_RUN) vendor/bin/phpstan analyse src

README.md

@@ -1,6 +1,6 @@
 # OpenAPI SDK generator - API client generator
 
-API client generator is a console application capable of auto-generating an API client based on OpenAPI specification according to PHP best practices, and your code style standards.
+API client generator is a console application capable of auto-generating a [PSR18](https://www.php-fig.org/psr/psr-18/)/[PSR7](https://www.php-fig.org/psr/psr-7/) compliant API client based on [OpenAPI v3](https://swagger.io/specification/) specification according to PHP best practices and your code style standards.
 
 [![Build Status](https://travis-ci.org/DoclerLabs/api-client-generator.svg?branch=master)](https://travis-ci.org/DoclerLabs/api-client-generator)
 [![Coverage Status](https://coveralls.io/repos/github/DoclerLabs/api-client-generator/badge.svg?branch=master)](https://coveralls.io/github/DoclerLabs/api-client-generator?branch=master)
@@ -9,7 +9,7 @@ API client generator is a console application capable of auto-generating an API
 ## Usage
 ### With Docker
 ```
-docker run -it \
+$ docker run -it \
 -v {path-to-specification}/openapi.yaml:/openapi.yaml:ro \
 -v {path-to-client}/some-api-client:/client \
 -e NAMESPACE=Group\\SomeApiClient \
@@ -45,5 +45,8 @@ The following environment variables are available:
 ## Running tests
 
 ```bash
-docker run  -w /app -v $(pwd):/app  php:7.4-cli-alpine php /app/vendor/bin/phpunit -c /app/phpunit.xml.dist --colors=always
+$ composer install
+$ make test
 ```
+
+(check `make` for all available routines).

src/Ast/Builder/CodeBuilder.php

@@ -129,13 +129,23 @@ public function appendToAssociativeArray(Variable $arrayVar, Expr $key, Expr $va
         return new Expression($this->assign($this->getArrayItem($arrayVar, $key), $value));
     }
 
-    public function localProperty(string $name, string $type, string $docType, Expr $default = null): Property
-    {
+    public function localProperty(
+        string $name,
+        string $type,
+        string $docType,
+        bool $nullable = false,
+        Expr $default = null
+    ): Property {
         $property = $this
             ->property($name)
             ->makePrivate();
 
         if ($this->phpVersion->isPropertyTypeHintSupported()) {
+            if ($nullable) {
+                $property->setDefault(null);
+                $type = '?' . $type;
+            }
+
             $property->setType($type);
         } else {
             $docComment = sprintf('/** @var %s */', $docType);

src/Generator/MutatorAccessorClassGeneratorAbstract.php

@@ -81,7 +81,8 @@ protected function generateProperty(Field $field): Property
         return $this->builder->localProperty(
             $field->getPhpVariableName(),
             $field->getPhpTypeHint(),
-            $field->getPhpDocType()
+            $field->getPhpDocType(),
+            $field->isOptional() || $field->isNullable()
         );
     }
 

src/Generator/SchemaGenerator.php

@@ -94,6 +94,7 @@ protected function generateConstructor(Field $root): ?ClassMethod
                 $paramsDoc[] = $this->builder
                     ->param($propertyField->getPhpVariableName())
                     ->setType($propertyField->getPhpTypeHint(), $propertyField->isNullable())
+                    ->setDocBlockType($propertyField->getPhpDocType($propertyField->isNullable()))
                     ->getNode();
             }
         }

src/Generator/SchemaMapperGenerator.php

@@ -275,7 +275,15 @@ protected function generateMapStatementsForObject(Field $root, Variable $payload
                 );
             } elseif ($field->isDate()) {
                 $this->addImport(DateTimeImmutable::class);
-                $requiredVars[] = $this->builder->new('DateTimeImmutable', [$requiredResponseItems[$i]]);
+                if ($field->isNullable()) {
+                    $requiredVars[] = $this->builder->ternary(
+                        $this->builder->notEquals($requiredResponseItems[$i], $this->builder->val(null)),
+                        $this->builder->new('DateTimeImmutable', [$requiredResponseItems[$i]]),
+                        $this->builder->val(null)
+                    );
+                } else {
+                    $requiredVars[] = $this->builder->new('DateTimeImmutable', [$requiredResponseItems[$i]]);
+                }
             } else {
                 $requiredVars[] = $requiredResponseItems[$i];
             }

src/Output/Copy/Response/ResponseHandler.php

@@ -20,11 +20,6 @@ public function __construct(BodySerializer $bodySerializer, ResponseExceptionFac
         $this->responseExceptionFactory = $exceptionFactory;
     }
 
-    /**
-     * @param ResponseInterface $response
-     *
-     * @return array
-     */
     public function handle(ResponseInterface $response): array
     {
         $statusCode = $response->getStatusCode();

src/Output/Copy/Schema/Mapper/SchemaMapperInterface.php

@@ -7,8 +7,6 @@
 interface SchemaMapperInterface
 {
     /**
-     * @param array $payload
-     *
      * @return SerializableInterface
      */
     public function toSchema(array $payload);

src/Output/Copy/Serializer/ContentType/Json/Json.php

@@ -11,8 +11,6 @@ class Json
      * @param mixed $data    Any data to encode.
      * @param int   $options Optional settings to pass to json_encode (@see json_encode).
      *
-     * @return string
-     *
      * @throws JsonException
      */
     public static function encode($data, int $options = 0): string
@@ -56,8 +54,6 @@ public static function getLastErrorMessage(): string
 
     /**
      * @param int $errorCode Error code to check for (@uses JSON_ERROR_*).
-     *
-     * @return string
      */
     public static function getErrorMessage(int $errorCode): string
     {

test/suite/functional/Generator/Client/SwaggerPetstoreClient.php

@@ -32,75 +32,42 @@ class SwaggerPetstoreClient
     /** @var ContainerInterface */
     private $container;
 
-    /**
-     * @param ClientInterface    $client
-     * @param ContainerInterface $container
-     */
     public function __construct(ClientInterface $client, ContainerInterface $container)
     {
         $this->client    = $client;
         $this->container = $container;
     }
 
-    /**
-     * @param RequestInterface $request
-     *
-     * @return ResponseInterface
-     */
     public function sendRequest(RequestInterface $request): ResponseInterface
     {
         return $this->client->sendRequest($this->container->get(RequestMapperInterface::class)->map($request));
     }
 
-    /**
-     * @param FindPetsRequest $request
-     *
-     * @return PetCollection
-     */
     public function findPets(FindPetsRequest $request): PetCollection
     {
         return $this->container->get(PetCollectionMapper::class)->toSchema($this->handleResponse($this->sendRequest($request)));
     }
 
-    /**
-     * @param AddPetRequest $request
-     *
-     * @return Pet
-     */
     public function addPet(AddPetRequest $request): Pet
     {
         return $this->container->get(PetMapper::class)->toSchema($this->handleResponse($this->sendRequest($request)));
     }
 
-    /**
-     * @param CountPetsRequest $request
-     */
     public function countPets(CountPetsRequest $request): void
     {
         $this->handleResponse($this->sendRequest($request));
     }
 
-    /**
-     * @param FindPetByIdRequest $request
-     *
-     * @return Pet
-     */
     public function findPetById(FindPetByIdRequest $request): Pet
     {
         return $this->container->get(PetMapper::class)->toSchema($this->handleResponse($this->sendRequest($request)));
     }
 
-    /**
-     * @param DeletePetsIdPetFoodFoodIdRequest $request
-     */
     public function deletePetsIdPetFoodFoodId(DeletePetsIdPetFoodFoodIdRequest $request): void
     {
         $this->handleResponse($this->sendRequest($request));
     }
 
-    /**
-     * @param ResponseInterface $response
-     */
     protected function handleResponse(ResponseInterface $response)
     {
         return $this->container->get(ResponseHandler::class)->handle($response);

test/suite/functional/Generator/ClientFactory/ClientFactoryDefault.php

@@ -15,11 +15,6 @@
 
 class SwaggerPetstoreClientFactory
 {
-    /**
-     * @param ClientInterface $client
-     *
-     * @return SwaggerPetstoreClient
-     */
     public function create(ClientInterface $client): SwaggerPetstoreClient
     {
         return new SwaggerPetstoreClient($client, $this->initContainer());

test/suite/functional/Generator/Request/GetResourcesRequest.php

@@ -21,23 +21,13 @@ class GetResourcesRequest implements RequestInterface
     /** @var int[]|null */
     private $filterByIds;
 
-    /**
-     * @param int $filterById
-     *
-     * @return self
-     */
     public function setFilterById(int $filterById): self
     {
         $this->filterById = $filterById;
 
         return $this;
     }
 
-    /**
-     * @param string $filterByName
-     *
-     * @return self
-     */
     public function setFilterByName(string $filterByName): self
     {
         $this->filterByName = $filterByName;
@@ -47,8 +37,6 @@ public function setFilterByName(string $filterByName): self
 
     /**
      * @param int[] $filterByIds
-     *
-     * @return self
      */
     public function setFilterByIds(array $filterByIds): self
     {
@@ -57,33 +45,21 @@ public function setFilterByIds(array $filterByIds): self
         return $this;
     }
 
-    /**
-     * @return string
-     */
     public function getContentType(): string
     {
         return '';
     }
 
-    /**
-     * @return string
-     */
     public function getMethod(): string
     {
         return 'GET';
     }
 
-    /**
-     * @return string
-     */
     public function getRoute(): string
     {
         return 'v1/resources';
     }
 
-    /**
-     * @return array
-     */
     public function getQueryParameters(): array
     {
         return \array_map(static function ($value) {
@@ -93,25 +69,16 @@ public function getQueryParameters(): array
         }));
     }
 
-    /**
-     * @return array
-     */
     public function getRawQueryParameters(): array
     {
         return ['filterById' => $this->filterById, 'filterByName' => $this->filterByName, 'filterByIds' => $this->filterByIds];
     }
 
-    /**
-     * @return array
-     */
     public function getCookies(): array
     {
         return [];
     }
 
-    /**
-     * @return array
-     */
     public function getHeaders(): array
     {
         return [];