Merge pull request #62 from memiah/master

Ability to include an external file as overview section.

.travis.yml

@@ -1,5 +1,7 @@
 language: php
 
+dist: trusty
+
 php:
   - 5.5.9
   - 5.5

src/Blueprint.php

@@ -71,16 +71,17 @@ protected function registerAnnotationLoader()
     }
 
     /**
-     * Generate documentation with the name and version.
+     * Generate documentation with the name, version and optional overview content.
      *
      * @param \Illuminate\Support\Collection $controllers
      * @param string                         $name
      * @param string                         $version
      * @param string                         $includePath
+     * @param string                         $overviewFile
      *
      * @return bool
      */
-    public function generate(Collection $controllers, $name, $version, $includePath = null)
+    public function generate(Collection $controllers, $name, $version, $includePath = null, $overviewFile = null)
     {
         $this->includePath = $includePath;
 
@@ -111,7 +112,7 @@ public function generate(Collection $controllers, $name, $version, $includePath
             return new RestResource($controller->getName(), $controller, $annotations, $actions);
         });
 
-        $contents = $this->generateContentsFromResources($resources, $name);
+        $contents = $this->generateContentsFromResources($resources, $name, $overviewFile);
 
         $this->includePath = null;
 
@@ -123,17 +124,19 @@ public function generate(Collection $controllers, $name, $version, $includePath
      *
      * @param \Illuminate\Support\Collection $resources
      * @param string                         $name
+     * @param string                         $overviewFile
      *
      * @return string
      */
-    protected function generateContentsFromResources(Collection $resources, $name)
+    protected function generateContentsFromResources(Collection $resources, $name, $overviewFile = null)
     {
         $contents = '';
 
         $contents .= $this->getFormat();
         $contents .= $this->line(2);
         $contents .= sprintf('# %s', $name);
         $contents .= $this->line(2);
+        $contents .= $this->getOverview($overviewFile);
 
         $resources->each(function ($resource) use (&$contents) {
             if ($resource->getActions()->isEmpty()) {
@@ -454,4 +457,29 @@ protected function getFormat()
     {
         return 'FORMAT: 1A';
     }
+
+    /**
+     * Get the overview file content to append.
+     *
+     * @param null $file
+     * @return null|string
+     */
+    protected function getOverview($file = null)
+    {
+        if (null !== $file) {
+            if (!file_exists($file)) {
+                throw new RuntimeException('Overview file could not be found.');
+            }
+
+            $content = file_get_contents($file);
+
+            if ($content === false) {
+                throw new RuntimeException('Failed to read overview file contents.');
+            }
+
+            return $content.$this->line(2);
+        }
+
+        return null;
+    }
 }

tests/BlueprintTest.php

@@ -487,4 +487,27 @@ public function testGeneratingSimpleBlueprints()
 
         $this->assertEquals(trim($expected), $blueprint->generate($resources, 'testing', 'v1', null));
     }
+
+    public function testGeneratingBlueprintOverview()
+    {
+        $resources = new Collection([new Stubs\ActivityController]);
+
+        $blueprint = new Blueprint(new SimpleAnnotationReader, new Filesystem);
+
+        $expected = <<<'EOT'
+FORMAT: 1A
+
+# testing
+
+Overview content here.
+
+# Activity
+
+## Show all activities. [GET /activity]
+EOT;
+
+        $this->assertEquals(trim($expected), $blueprint->generate($resources, 'testing', 'v1', null, __DIR__.'/Files/overview.apib'));
+
+
+    }
 }

tests/Files/overview.apib

@@ -0,0 +1 @@
+Overview content here.