DocumentationGeneratorRestApi feature integration

Install feature API

Prerequisites

To start feature integration, overview and install the necessary features:

1) Install the required modules using Composer

Run the following command to install the required modules: composer require spryker/documentation-generator-rest-api:"^1.2.0" spryker/documentation-generator-rest-api-extension:"^1.0.0" --update-with-dependencies

2) Set up Transfer objects

Run the following command to generate transfer changes: console transfer:generate

3) Set up behavior

Configure REST attributes transfers

Implementation Update all the needed RestAttributes transfer objects definitions on the project level to add restRequestParameter to the properties that should be included in the request object for the endpoint. For example:

<transfer name="RestAccessTokensAttributes">
    <property name="username" type="string" restRequestParameter="required" />
    <property name="password" type="string" restRequestParameter="required" />
    <property name="tokenType" type="string" />
    <property name="expiresIn" type="string" />
    <property name="accessToken" type="string" />
    <property name="refreshToken" type="string" />
</transfer>

restRequestParameter can accept one of the three values:

• required - property will be marked as required in the request body schema.
• yes - property will be marked as optional in the request body schema.
• no - property will be skipped in the request body schema.

By default, every property is considered as not needed and will be skipped in the schema definition. Run the following command to generate the transfer changes: console transfer:generate

Verification

The annotation object should consist of a top-level object with one property that represents the request method used. It can be one of these:

• getCollection, getResource - for the GET requests
• post, patch, delete - respectively for the POST, PATCH, DELETE requests

Currently supported annotation properties:

• summary - summary of an endpoint. If not specified, summary will be generated from the resource type.
• parameters - parameters that can be passed with the request. (see https://swagger.io/specification/#parameterObject).
• responses - all the possible response codes and their descriptions for a given endpoint.
• responseClass - defines a custom transfer class that represents a response object (in cases when the request and response objects are different); FQCN needed.
• isEmptyResponse - should be set to true when a method does not have a response body (no need to set it in the delete methods as they have an empty response body by default)

Enable console command

Activate the following plugin:

src/Pyz/Zed/Console/ConsoleDependencyProvider.php

<?php
  
namespace Pyz\Zed\Console;
 
use Spryker\Zed\Console\ConsoleDependencyProvider as SprykerConsoleDependencyProvider;
use Spryker\Zed\DocumentationGeneratorRestApi\Communication\Console\GenerateRestApiDocumentationConsole;
  
class ConsoleDependencyProvider extends SprykerConsoleDependencyProvider
{
    /**
     * @param \Spryker\Zed\Kernel\Container $container
     *
     * @return \Symfony\Component\Console\Command\Command[]
     */
    protected function getConsoleCommands(Container $container)
    {
        $commands = [
            new GenerateRestApiDocumentationConsole(),
        ];
  
        return $commands;
    }
}

Enable documentation generator

Activate the following plugins:

src/Pyz/Zed/DocumentationGeneratorRestApi/DocumentationGeneratorRestApiDependencyProvider.php

<?php
 
namespace Pyz\Zed\DocumentationGeneratorRestApi;
 
use Spryker\Glue\GlueApplication\Plugin\DocumentationGeneratorRestApi\ResourceRelationshipCollectionProviderPlugin;
use Spryker\Glue\GlueApplication\Plugin\DocumentationGeneratorRestApi\ResourceRoutePluginsProviderPlugin;
use Spryker\Zed\DocumentationGeneratorRestApi\DocumentationGeneratorRestApiDependencyProvider as SprykerDocumentationGeneratorRestApiDependencyProvider;
 
class DocumentationGeneratorRestApiDependencyProvider extends SprykerDocumentationGeneratorRestApiDependencyProvider
{
    /**
     * @return \Spryker\Glue\DocumentationGeneratorRestApiExtension\Dependency\Plugin\ResourceRoutePluginsProviderPluginInterface[]
     */
    protected function getResourceRoutePluginProviderPlugins(): array
    {
        return [
            new ResourceRoutePluginsProviderPlugin(),
        ];
    }
 
    /**
     * @return \Spryker\Glue\DocumentationGeneratorRestApiExtension\Dependency\Plugin\ResourceRelationshipCollectionProviderPluginInterface[]
     */
    protected function getResourceRelationshipCollectionProviderPlugins(): array
    {
        return [
            new ResourceRelationshipCollectionProviderPlugin(),
        ];
    }
}

Last review date: Feb 25, 2019