feat: Refactor Documentation and Entrypoint support (#628)

Author: Simperfit

features/custom_identifier.feature

@@ -82,7 +82,7 @@ Feature: Using custom identifier on resource
       """
 
   Scenario: API doc is correctly generated
-    When I send a "GET" request to "/apidoc"
+    When I send a "GET" request to "/apidoc.jsonld"
     Then the response status code should be 200
     And the response should be in JSON
     And the hydra class "CustomIdentifierDummy" exist

features/custom_normalized.feature

@@ -87,7 +87,7 @@ Feature: Using custom normalized entity
       """
 
   Scenario: API doc is correctly generated
-    When I send a "GET" request to "/apidoc"
+    When I send a "GET" request to "/apidoc.jsonld"
     Then the response status code should be 200
     And the response should be in JSON
     And the hydra class "CustomNormalizedDummy" exist

features/custom_writable_identifier.feature

@@ -84,7 +84,7 @@ Feature: Using custom writable identifier on resource
       """
 
   Scenario: API doc is correctly generated
-    When I send a "GET" request to "/apidoc"
+    When I send a "GET" request to "/apidoc.jsonld"
     Then the response status code should be 200
     And the response should be in JSON
     And the hydra class "CustomWritableIdentifierDummy" exist

features/hydra/doc.feature

@@ -5,15 +5,15 @@ Feature: Documentation support
 
   Scenario: Checks that the Link pointing to the Hydra documentation is set
     Given I send a "GET" request to "/"
-    Then the header "Link" should be equal to '<http://example.com/apidoc>; rel="http://www.w3.org/ns/hydra/core#apiDocumentation"'
+    Then the header "Link" should be equal to '<http://example.com/apidoc.jsonld>; rel="http://www.w3.org/ns/hydra/core#apiDocumentation"'
 
   Scenario: Retrieve the API vocabulary
-    Given I send a "GET" request to "/apidoc"
+    Given I send a "GET" request to "/apidoc.jsonld"
     Then the response status code should be 200
     And the response should be in JSON
     And the header "Content-Type" should be equal to "application/ld+json"
     # Context
-    And the JSON node "@context.@vocab" should be equal to "http://example.com/apidoc#"
+    And the JSON node "@context.@vocab" should be equal to "http://example.com/apidoc.jsonld#"
     And the JSON node "@context.hydra" should be equal to "http://www.w3.org/ns/hydra/core#"
     And the JSON node "@context.rdf" should be equal to "http://www.w3.org/1999/02/22-rdf-syntax-ns#"
     And the JSON node "@context.rdfs" should be equal to "http://www.w3.org/2000/01/rdf-schema#"
@@ -30,7 +30,7 @@ Feature: Documentation support
     And the JSON node "@context.returns.@id" should be equal to "hydra:returns"
     And the JSON node "@context.returns.@type" should be equal to "@id"
     # Root properties
-    And the JSON node "@id" should be equal to "/apidoc"
+    And the JSON node "@id" should be equal to "/apidoc.jsonld"
     And the JSON node "hydra:title" should be equal to "My Dummy API"
     And the JSON node "hydra:description" should be equal to "This is a test API."
     And the JSON node "hydra:entrypoint" should be equal to "/"

features/jsonld/context.feature

@@ -36,7 +36,7 @@ Feature: JSON-LD contexts generation
     """
       {
           "@context": {
-              "@vocab": "http://example.com/apidoc#",
+              "@vocab": "http://example.com/apidoc.jsonld#",
               "hydra": "http://www.w3.org/ns/hydra/core#",
               "description": "https://schema.org/description",
               "dummy": "#Dummy/dummy",
@@ -69,7 +69,7 @@ Feature: JSON-LD contexts generation
       """
       {
         "@context": {
-          "@vocab": "http://example.com/apidoc#",
+          "@vocab": "http://example.com/apidoc.jsonld#",
           "hydra": "http://www.w3.org/ns/hydra/core#",
           "paris": "#RelationEmbedder/paris",
           "krondstadt": "#RelationEmbedder/krondstadt",

features/swagger/doc.feature

@@ -4,7 +4,7 @@ Feature: Documentation support
   I need to know Swagger specifications of objects I send and receive
 
   Scenario: Retrieve the API vocabulary
-    Given I send a "GET" request to "/swagger"
+    Given I send a "GET" request to "/apidoc.json"
     Then the response status code should be 200
     And the response should be in JSON
     And the header "Content-Type" should be equal to "application/json"

src/Action/EntrypointAction.php

@@ -11,8 +11,8 @@
 
 namespace ApiPlatform\Core\Action;
 
+use ApiPlatform\Core\Api\Entrypoint;
 use ApiPlatform\Core\Metadata\Resource\Factory\ResourceNameCollectionFactoryInterface;
-use ApiPlatform\Core\Metadata\Resource\ResourceNameCollection;
 
 /**
  * Generates the API entrypoint.
@@ -23,13 +23,13 @@ final class EntrypointAction
 {
     private $resourceNameCollectionFactory;
 
-    public function __construct(ResourceNameCollectionFactoryInterface $resourceNameCollection)
+    public function __construct(ResourceNameCollectionFactoryInterface $resourceNameCollectionFactory)
     {
-        $this->resourceNameCollectionFactory = $resourceNameCollection;
+        $this->resourceNameCollectionFactory = $resourceNameCollectionFactory;
     }
 
-    public function __invoke() : ResourceNameCollection
+    public function __invoke() : Entrypoint
     {
-        return $this->resourceNameCollectionFactory->create();
+        return new Entrypoint($this->resourceNameCollectionFactory->create());
     }
 }

src/Api/Entrypoint.php

@@ -0,0 +1,34 @@
+<?php
+
+/*
+ * This file is part of the API Platform project.
+ *
+ * (c) Kévin Dunglas <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace ApiPlatform\Core\Api;
+
+use ApiPlatform\Core\Metadata\Resource\ResourceNameCollection;
+
+/**
+ * The first path you will see in the API.
+ *
+ * @author Amrouche Hamza <[email protected]>
+ */
+final class Entrypoint
+{
+    private $resourceNameCollection;
+
+    public function __construct(ResourceNameCollection $resourceNameCollection)
+    {
+        $this->resourceNameCollection = $resourceNameCollection;
+    }
+
+    public function getResourceNameCollection(): ResourceNameCollection
+    {
+        return $this->resourceNameCollection;
+    }
+}

src/Bridge/NelmioApiDoc/Extractor/AnnotationsProvider/ApiPlatformProvider.php

@@ -14,13 +14,13 @@
 use ApiPlatform\Core\Api\FilterCollection;
 use ApiPlatform\Core\Bridge\NelmioApiDoc\Parser\ApiPlatformParser;
 use ApiPlatform\Core\Bridge\Symfony\Routing\OperationMethodResolverInterface;
-use ApiPlatform\Core\Documentation\ApiDocumentationBuilderInterface;
 use ApiPlatform\Core\Metadata\Resource\Factory\ResourceMetadataFactoryInterface;
 use ApiPlatform\Core\Metadata\Resource\Factory\ResourceNameCollectionFactoryInterface;
 use ApiPlatform\Core\Metadata\Resource\ResourceMetadata;
 use Nelmio\ApiDocBundle\Annotation\ApiDoc;
 use Nelmio\ApiDocBundle\Extractor\AnnotationsProviderInterface;
 use Symfony\Component\HttpFoundation\Request;
+use Symfony\Component\Serializer\Normalizer\NormalizerInterface;
 
 /**
  * Creates Nelmio ApiDoc annotations for the api platform.
@@ -31,15 +31,15 @@
 final class ApiPlatformProvider implements AnnotationsProviderInterface
 {
     private $resourceNameCollectionFactory;
-    private $apiDocumentationBuilder;
+    private $documentationNormalizer;
     private $resourceMetadataFactory;
     private $filters;
     private $operationMethodResolver;
 
-    public function __construct(ResourceNameCollectionFactoryInterface $resourceNameCollectionFactory, ApiDocumentationBuilderInterface $apiDocumentationBuilder, ResourceMetadataFactoryInterface $resourceMetadataFactory, FilterCollection $filters, OperationMethodResolverInterface $operationMethodResolver)
+    public function __construct(ResourceNameCollectionFactoryInterface $resourceNameCollectionFactory, NormalizerInterface $documentationNormalizer, ResourceMetadataFactoryInterface $resourceMetadataFactory, FilterCollection $filters, OperationMethodResolverInterface $operationMethodResolver)
     {
         $this->resourceNameCollectionFactory = $resourceNameCollectionFactory;
-        $this->apiDocumentationBuilder = $apiDocumentationBuilder;
+        $this->documentationNormalizer = $documentationNormalizer;
         $this->resourceMetadataFactory = $resourceMetadataFactory;
         $this->filters = $filters;
         $this->operationMethodResolver = $operationMethodResolver;
@@ -51,7 +51,7 @@ public function __construct(ResourceNameCollectionFactoryInterface $resourceName
     public function getAnnotations() : array
     {
         $annotations = [];
-        $hydraDoc = $this->apiDocumentationBuilder->getApiDocumentation();
+        $hydraDoc = $this->documentationNormalizer->normalize($this->resourceNameCollectionFactory->create());
         $entrypointHydraDoc = $this->getResourceHydraDoc($hydraDoc, '#Entrypoint');
 
         foreach ($this->resourceNameCollectionFactory->create() as $resourceClass) {

src/Bridge/Symfony/Bundle/Command/SwaggerCommand.php

@@ -11,7 +11,9 @@
 
 namespace ApiPlatform\Core\Bridge\Symfony\Bundle\Command;
 
-use ApiPlatform\Core\Swagger\ApiDocumentationBuilder;
+use ApiPlatform\Core\Documentation\Documentation;
+use ApiPlatform\Core\Metadata\Resource\Factory\ResourceNameCollectionFactoryInterface;
+use ApiPlatform\Core\Swagger\DocumentationNormalizer;
 use Symfony\Component\Console\Command\Command;
 use Symfony\Component\Console\Input\InputInterface;
 use Symfony\Component\Console\Output\OutputInterface;
@@ -23,12 +25,22 @@
  */
 final class SwaggerCommand extends Command
 {
-    private $apiDocumentationBuilder;
+    private $documentationNormalizer;
+    private $resourceNameCollectionFactory;
+    private $title;
+    private $description;
+    private $version;
+    private $formats;
 
-    public function __construct(ApiDocumentationBuilder $apiDocumentationBuilder)
+    public function __construct(DocumentationNormalizer $documentationNormalizer, ResourceNameCollectionFactoryInterface $resourceNameCollection, string $title, string $description, string $version, array $formats)
     {
         parent::__construct();
-        $this->apiDocumentationBuilder = $apiDocumentationBuilder;
+        $this->documentationNormalizer = $documentationNormalizer;
+        $this->resourceNameCollectionFactory = $resourceNameCollection;
+        $this->title = $title;
+        $this->description = $description;
+        $this->version = $version;
+        $this->formats = $formats;
     }
 
     /**
@@ -46,7 +58,8 @@ protected function configure()
      */
     protected function execute(InputInterface $input, OutputInterface $output)
     {
-        $data = $this->apiDocumentationBuilder->getApiDocumentation();
+        $documentation = new Documentation($this->resourceNameCollectionFactory->create(), $this->title, $this->description, $this->version, $this->formats);
+        $data = $this->documentationNormalizer->normalize($documentation);
         $content = json_encode($data, JSON_PRETTY_PRINT);
         $output->writeln($content);
     }