From 990ed7c7e0b66bbc1e29206d3ca64d2bf33bd42f Mon Sep 17 00:00:00 2001
From: memiah-steve <steve@memiah.co.uk>
Date: Thu, 29 Jun 2017 15:04:40 +0100
Subject: [PATCH 1/3] Ability to include an external file as the blueprint
 overview.

---
 src/Blueprint.php         | 33 ++++++++++++++++++++++++++++++---
 tests/BlueprintTest.php   | 23 +++++++++++++++++++++++
 tests/Files/overview.apib |  1 +
 3 files changed, 54 insertions(+), 3 deletions(-)
 create mode 100644 tests/Files/overview.apib

diff --git a/src/Blueprint.php b/src/Blueprint.php
index b95a66e..e88c48c 100644
--- a/src/Blueprint.php
+++ b/src/Blueprint.php
@@ -80,7 +80,7 @@ protected function registerAnnotationLoader()
      *
      * @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 +111,7 @@ public function generate(Collection $controllers, $name, $version, $includePath
             return new Resource($controller->getName(), $controller, $annotations, $actions);
         });
 
-        $contents = $this->generateContentsFromResources($resources, $name);
+        $contents = $this->generateContentsFromResources($resources, $name, $overviewFile);
 
         $this->includePath = null;
 
@@ -123,10 +123,11 @@ 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 = '';
 
@@ -134,6 +135,7 @@ protected function generateContentsFromResources(Collection $resources, $name)
         $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 +456,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;
+    }
 }
diff --git a/tests/BlueprintTest.php b/tests/BlueprintTest.php
index e37a019..283b1ca 100644
--- a/tests/BlueprintTest.php
+++ b/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'));
+
+
+    }
 }
diff --git a/tests/Files/overview.apib b/tests/Files/overview.apib
new file mode 100644
index 0000000..ded8ecc
--- /dev/null
+++ b/tests/Files/overview.apib
@@ -0,0 +1 @@
+Overview content here.
\ No newline at end of file

From 3c014e85349038b2893346f4eff6833f10365d58 Mon Sep 17 00:00:00 2001
From: memiah-steve <steve@memiah.co.uk>
Date: Thu, 29 Jun 2017 15:09:12 +0100
Subject: [PATCH 2/3] Update PHP docs to include overview file.

---
 src/Blueprint.php | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/Blueprint.php b/src/Blueprint.php
index e88c48c..971c85d 100644
--- a/src/Blueprint.php
+++ b/src/Blueprint.php
@@ -71,12 +71,13 @@ 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
      */

From 0374ae7695e972c86e40734ac4475652de477c11 Mon Sep 17 00:00:00 2001
From: memiah-steve <steve@memiah.co.uk>
Date: Thu, 29 Jun 2017 16:28:13 +0100
Subject: [PATCH 3/3] Use Trusty dist for Travis CI.

---
 .travis.yml | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/.travis.yml b/.travis.yml
index 35bd6f4..60a2f59 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -1,5 +1,7 @@
 language: php
 
+dist: trusty
+
 php:
   - 5.5.9
   - 5.5