Merge pull request #237 from vimeo/add-info-description

Adding support for OpenAPI API info descriptions

config.xsd

@@ -17,6 +17,8 @@
             <xs:element name="info" minOccurs="1" maxOccurs="1">
                 <xs:complexType>
                     <xs:sequence>
+                        <xs:element name="description" minOccurs="1" maxOccurs="unbounded" />
+
                         <xs:element name="terms" minOccurs="0" maxOccurs="1">
                             <xs:complexType>
                                 <xs:attribute name="url" type="xs:string" use="required" />

resources/examples/Showtimes/compiled/1.0/openapi/api.yaml

@@ -1,6 +1,7 @@
 openapi: 3.0.2
 info:
   title: 'Mill unit test API, Showtimes'
+  description: 'This is an example API for the purposes of showing how Mill works.'
   version: '1.0'
   contact:
     name: 'Get help!'

resources/examples/Showtimes/compiled/1.0/openapi/tags/Movies.yaml

@@ -1,6 +1,7 @@
 openapi: 3.0.2
 info:
   title: 'Mill unit test API, Showtimes'
+  description: 'This is an example API for the purposes of showing how Mill works.'
   version: '1.0'
   contact:
     name: 'Get help!'

resources/examples/Showtimes/compiled/1.0/openapi/tags/Theaters.yaml

@@ -1,6 +1,7 @@
 openapi: 3.0.2
 info:
   title: 'Mill unit test API, Showtimes'
+  description: 'This is an example API for the purposes of showing how Mill works.'
   version: '1.0'
   contact:
     name: 'Get help!'

resources/examples/Showtimes/compiled/1.1.1/openapi/api.yaml

@@ -1,6 +1,7 @@
 openapi: 3.0.2
 info:
   title: 'Mill unit test API, Showtimes'
+  description: 'This is an example API for the purposes of showing how Mill works.'
   version: 1.1.1
   contact:
     name: 'Get help!'

resources/examples/Showtimes/compiled/1.1.1/openapi/tags/Movies.yaml

@@ -1,6 +1,7 @@
 openapi: 3.0.2
 info:
   title: 'Mill unit test API, Showtimes'
+  description: 'This is an example API for the purposes of showing how Mill works.'
   version: 1.1.1
   contact:
     name: 'Get help!'

resources/examples/Showtimes/compiled/1.1.1/openapi/tags/Theaters.yaml

@@ -1,6 +1,7 @@
 openapi: 3.0.2
 info:
   title: 'Mill unit test API, Showtimes'
+  description: 'This is an example API for the purposes of showing how Mill works.'
   version: 1.1.1
   contact:
     name: 'Get help!'

resources/examples/Showtimes/compiled/1.1.2/openapi/api.yaml

@@ -1,6 +1,7 @@
 openapi: 3.0.2
 info:
   title: 'Mill unit test API, Showtimes'
+  description: 'This is an example API for the purposes of showing how Mill works.'
   version: 1.1.2
   contact:
     name: 'Get help!'

resources/examples/Showtimes/compiled/1.1.2/openapi/tags/Movies.yaml

@@ -1,6 +1,7 @@
 openapi: 3.0.2
 info:
   title: 'Mill unit test API, Showtimes'
+  description: 'This is an example API for the purposes of showing how Mill works.'
   version: 1.1.2
   contact:
     name: 'Get help!'

resources/examples/Showtimes/compiled/1.1.2/openapi/tags/Theaters.yaml

@@ -1,6 +1,7 @@
 openapi: 3.0.2
 info:
   title: 'Mill unit test API, Showtimes'
+  description: 'This is an example API for the purposes of showing how Mill works.'
   version: 1.1.2
   contact:
     name: 'Get help!'

resources/examples/Showtimes/compiled/1.1.3/openapi/api.yaml

@@ -1,6 +1,7 @@
 openapi: 3.0.2
 info:
   title: 'Mill unit test API, Showtimes'
+  description: 'This is an example API for the purposes of showing how Mill works.'
   version: 1.1.3
   contact:
     name: 'Get help!'

resources/examples/Showtimes/compiled/1.1.3/openapi/tags/Movies.yaml

@@ -1,6 +1,7 @@
 openapi: 3.0.2
 info:
   title: 'Mill unit test API, Showtimes'
+  description: 'This is an example API for the purposes of showing how Mill works.'
   version: 1.1.3
   contact:
     name: 'Get help!'

resources/examples/Showtimes/compiled/1.1.3/openapi/tags/Theaters.yaml

@@ -1,6 +1,7 @@
 openapi: 3.0.2
 info:
   title: 'Mill unit test API, Showtimes'
+  description: 'This is an example API for the purposes of showing how Mill works.'
   version: 1.1.3
   contact:
     name: 'Get help!'

resources/examples/Showtimes/compiled/1.1/openapi/api.yaml

@@ -1,6 +1,7 @@
 openapi: 3.0.2
 info:
   title: 'Mill unit test API, Showtimes'
+  description: 'This is an example API for the purposes of showing how Mill works.'
   version: '1.1'
   contact:
     name: 'Get help!'

resources/examples/Showtimes/compiled/1.1/openapi/tags/Movies.yaml

@@ -1,6 +1,7 @@
 openapi: 3.0.2
 info:
   title: 'Mill unit test API, Showtimes'
+  description: 'This is an example API for the purposes of showing how Mill works.'
   version: '1.1'
   contact:
     name: 'Get help!'

resources/examples/Showtimes/compiled/1.1/openapi/tags/Theaters.yaml

@@ -1,6 +1,7 @@
 openapi: 3.0.2
 info:
   title: 'Mill unit test API, Showtimes'
+  description: 'This is an example API for the purposes of showing how Mill works.'
   version: '1.1'
   contact:
     name: 'Get help!'

resources/examples/Showtimes/compiled/public/1.0/api.yaml

@@ -1,6 +1,7 @@
 openapi: 3.0.2
 info:
   title: 'Mill unit test API, Showtimes'
+  description: 'This is an example API for the purposes of showing how Mill works.'
   version: '1.0'
   contact:
     name: 'Get help!'

resources/examples/Showtimes/compiled/public/1.1.1/api.yaml

@@ -1,6 +1,7 @@
 openapi: 3.0.2
 info:
   title: 'Mill unit test API, Showtimes'
+  description: 'This is an example API for the purposes of showing how Mill works.'
   version: 1.1.1
   contact:
     name: 'Get help!'

resources/examples/Showtimes/compiled/public/1.1.2/api.yaml

@@ -1,6 +1,7 @@
 openapi: 3.0.2
 info:
   title: 'Mill unit test API, Showtimes'
+  description: 'This is an example API for the purposes of showing how Mill works.'
   version: 1.1.2
   contact:
     name: 'Get help!'

resources/examples/Showtimes/compiled/public/1.1.3/api.yaml

@@ -1,6 +1,7 @@
 openapi: 3.0.2
 info:
   title: 'Mill unit test API, Showtimes'
+  description: 'This is an example API for the purposes of showing how Mill works.'
   version: 1.1.3
   contact:
     name: 'Get help!'

resources/examples/Showtimes/compiled/public/1.1/api.yaml

@@ -1,6 +1,7 @@
 openapi: 3.0.2
 info:
   title: 'Mill unit test API, Showtimes'
+  description: 'This is an example API for the purposes of showing how Mill works.'
   version: '1.1'
   contact:
     name: 'Get help!'

resources/examples/mill.xml

@@ -4,6 +4,8 @@
     bootstrap="../../vendor/autoload.php"
 >
     <info>
+        <description>This is an example API for the purposes of showing how Mill works.</description>
+
         <terms url="https://example.com/terms" />
 
         <contact

src/Compiler/Specification/OpenApi.php

@@ -56,6 +56,7 @@ public function compile(): void
                 'openapi' => '3.0.2',
                 'info' => [
                     'title' => $this->config->getName(),
+                    'description' => $this->config->getDescription(),
                     'version' => $version,
                     'contact' => $this->processContact()
                 ],

src/Config.php

@@ -28,8 +28,11 @@ class Config
     /** @var string The base directory for this configuration file. */
     protected $base_dir;
 
-    /** @var null|string The name of your API. */
-    protected $name = null;
+    /** @var string The name of your API. */
+    protected $name;
+
+    /** @var string The description of your API. */
+    protected $description;
 
     /** @var null|string The terms of service URL for your API. */
     protected $terms = null;
@@ -306,6 +309,10 @@ protected function loadCompilerSettings(SimpleXMLElement $xml): void
      */
     protected function loadInfo(SimpleXMLElement $xml): void
     {
+        if (isset($xml->info->description)) {
+            $this->description = (string) $xml->info->description;
+        }
+
         if (isset($xml->info->terms)) {
             $this->terms = (string) $xml->info->terms['url'];
         }
@@ -543,13 +550,23 @@ protected function loadErrorRepresentations(SimpleXMLElement $xml): void
     /**
      * Get the name of your API.
      *
-     * @return null|string
+     * @return string
      */
-    public function getName(): ?string
+    public function getName(): string
     {
         return $this->name;
     }
 
+    /**
+     * Get the description of your API.
+     *
+     * @return string
+     */
+    public function getDescription(): string
+    {
+        return $this->description;
+    }
+
     /**
      * Get the terms of service URL for your API.
      *

tests/ConfigTest.php

@@ -12,6 +12,11 @@ public function testLoadFromXML(): void
         $config = $this->getConfig();
 
         $this->assertSame('Mill unit test API, Showtimes', $config->getName());
+        $this->assertSame(
+            'This is an example API for the purposes of showing how Mill works.',
+            $config->getDescription()
+        );
+
         $this->assertSame('https://example.com/terms', $config->getTerms());
 
         $this->assertSame([
@@ -230,6 +235,8 @@ public function testLoadFromXMLFailuresOnVariousBadXMLFiles(array $exception_det
         if (strpos($provider, 'info.') === false) {
             $info = <<<XML
 <info>
+    <description>This is an example API for the purposes of showing how Mill works.</description>
+
     <terms url="https://example.com/terms" />
 
     <contact

tests/_fixtures/mill.test.xml

@@ -4,6 +4,8 @@
     bootstrap="vendor/autoload.php"
 >
     <info>
+        <description>This is an example API for the purposes of showing how Mill works.</description>
+
         <terms url="https://example.com/terms" />
 
         <contact